5.7.6 代码规范、版本管理与审计

代码规范、版本管理与审计是脚本治理的核心，目标是“可读、可控、可追溯”。本节从规范、版本管理与审计三条线给出可执行落地方案，并提供安装、示例、排错与练习。

原理草图（规范-版本-审计闭环）：

一、代码规范与静态检查#

推荐规范要点
- 统一脚本头部、严格模式、函数命名与变量命名约定
- 明确输入/输出与退出码
- 依赖命令显式校验

示例：规范模板与注释说明（可直接复制为模板）

#!/usr/bin/env bash
# 文件: /opt/scripts/backup_db.sh
# 作用: 备份MySQL数据库并校验结果
set -euo pipefail

# 全局常量
readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly LOG_DIR="/var/log/ops"
readonly DATE="$(date +%F)"
readonly DB_HOST="${DB_HOST:-127.0.0.1}"
readonly DB_USER="${DB_USER:-backup}"
readonly DB_NAME="${DB_NAME:-app}"

# 依赖检查
need_cmd() { command -v "$1" >/dev/null 2>&1 || { echo "缺少命令: $1"; exit 127; }; }
need_cmd mysqldump
need_cmd gzip

# 日志函数
log() { printf "%s %s\n" "$(date '+%F %T')" "$*" >> "${LOG_DIR}/backup_db.log"; }

# 参数解析
usage() { echo "用法: $0 -p <db_password>"; exit 2; }
DB_PASS=""
while getopts "p:" opt; do
  case "$opt" in
    p) DB_PASS="$OPTARG" ;;
    *) usage ;;
  esac
done
[[ -z "$DB_PASS" ]] && usage

# 业务逻辑
backup_file="/data/backup/${DB_NAME}_${DATE}.sql.gz"
mysqldump -h "$DB_HOST" -u "$DB_USER" -p"$DB_PASS" "$DB_NAME" | gzip > "$backup_file"
log "备份完成: $backup_file"
echo "OK: $backup_file"

静态检查工具安装与使用（ShellCheck）

# 安装(以 Ubuntu/Debian 为例)
apt-get update && apt-get install -y shellcheck

# 扫描脚本
shellcheck /opt/scripts/backup_db.sh
# 预期: 若无问题，输出为空；有问题会提示行号与建议

常见排错
- SC2086：变量未加引号导致分词
修复："$var"
- command not found：缺少依赖
修复：增加 need_cmd 校验并安装依赖

---

二、版本管理与发布规范#

推荐流程
- 主干/特性分支
- 提交前本地检查（ShellCheck + 单元测试）
- 合并请求（MR）+ 代码评审 + 标签版本

示例：最小可执行 Git 流程

# 初始化仓库
mkdir -p /opt/ops-scripts && cd /opt/ops-scripts
git init

# 添加脚本
cp /opt/scripts/backup_db.sh .
git add backup_db.sh
git commit -m "feat(backup): add mysql backup script"

# 创建特性分支
git checkout -b feat/backup-verify

# 修改后提交
sed -i 's/备份完成/备份完成并校验/' backup_db.sh
git add backup_db.sh
git commit -m "chore(backup): update log message"

# 合并到主干
git checkout main
git merge feat/backup-verify

# 打标签发布
git tag -a v1.0.0 -m "release: mysql backup script v1.0.0"
git push --tags

发布包建议结构

release/
├── scripts/
│   └── backup_db.sh
├── conf/
│   └── backup_db.env.example
└── CHANGELOG.md

发布包生成示例

mkdir -p release/scripts release/conf
cp backup_db.sh release/scripts/
cat > release/conf/backup_db.env.example <<'EOF'
DB_HOST=127.0.0.1
DB_USER=backup
DB_NAME=app
DB_PASS=change_me
EOF

cat > release/CHANGELOG.md <<'EOF'
# v1.0.0
- 新增 MySQL 备份脚本
- 支持环境变量与参数传入
EOF

tar -czf ops-scripts-v1.0.0.tar.gz release
echo "发布包生成: ops-scripts-v1.0.0.tar.gz"

排错
- merge conflict：先 git status 查看冲突文件，手动修复后 git add 再提交
- tag already exists：使用新版本号或删除旧标签 git tag -d v1.0.0

---

三、审计机制与落地实现#

审计包括三类：代码审计、执行审计、变更审计。建议每次执行都落日志，记录用户、主机、时间、脚本版本。

执行审计落地示例（日志统一格式）

# 文件: /opt/scripts/common_audit.sh
audit_log="/var/log/ops/exec_audit.log"
audit() {
  local script_name="$1"
  local version="$2"
  local status="$3"
  printf "%s user=%s host=%s script=%s version=%s status=%s\n" \
    "$(date '+%F %T')" "$(whoami)" "$(hostname)" "$script_name" "$version" "$status" \
    >> "$audit_log"
}

在脚本中调用：

# 在 backup_db.sh 中增加
VERSION="v1.0.0"
source /opt/scripts/common_audit.sh

# 成功/失败处记录
audit "backup_db.sh" "$VERSION" "success"
# 若失败可捕获:
trap 'audit "backup_db.sh" "$VERSION" "failed"; exit 1' ERR

变更审计
- Git 提交记录与 MR 评审记录
- 发布包版本号与变更说明（CHANGELOG）
- 变更工单号（可记录到提交信息或 CHANGELOG）

---

四、练习与验证#

1) 规范检查练习
- 手写脚本 hello.sh，开启 set -euo pipefail，然后运行 shellcheck hello.sh，修复所有警告。

2) 版本发布练习
- 用 Git 创建标签 v0.1.0，生成发布包，并写入 CHANGELOG。

3) 审计日志练习
- 在脚本中引入 common_audit.sh，执行脚本后查看 /var/log/ops/exec_audit.log 是否记录完整字段。

4) 排错练习
- 故意删除 gzip 命令，运行脚本观察 need_cmd 报错，安装后再次执行。