feat: 新增 Docker Compose 部署方案, 移除未验证的 ansible 草案

原 ansible/ 方案从未在任何环境验证过, 且与本机实际状态严重不符(硬编码
amd64 二进制、会覆盖生产 /etc/gitea/app.ini、会启动 firewalld 切断其它
服务、建的库名与现网不一致); 加上宿主机 Rocky 8 的系统 Python 无法升级,
新版 ansible 也跑不起来。改为 Docker Compose。

新增 deploy/:
- compose.yaml    版本锁定; Gitea 只发布 127.0.0.1:2080(Apache 反代无需
                  改动), PostgreSQL 不发布端口; 配置全部由
                  GITEA__section__KEY 环境变量注入; 数据用 bind mount
- db/Dockerfile   官方 postgres 只生成 en_US.UTF-8, 这里补 zh_CN.UTF-8,
                  与现有集群 collation 保持一致
- scripts/        backup.sh(pg_dump + 数据 tar + SHA256SUMS)、
                  restore.sh(默认 dry-run, 校验后还原, 拒收宿主布局备份)、
                  verify.sh(容器健康 + 回环 API + 经 Apache 反代)

文档 deploy/README.md 以 部署/备份/恢复/升级 四条流程为主线, 并记录本机
踩过的四个陷阱: PG18 挂载点、s6 chown 守卫、APP_NAME 只能走裸变量、
HTTP 代理导致的假 502。

一次性迁移脚本(install-docker / configure-docker-proxy / preflight /
migrate-from-binary)已清理, 相应步骤内联进文档。

实测: 源 116 表 → 目标 116 表, /api/healthz 200, 经 Apache /QA 200,
站点名与 OIDC 登录源注册正常。
This commit is contained in:
2026-09-11 16:00:15 +08:00
parent 66c254e0ff
commit 79256c5be0
26 changed files with 1590 additions and 779 deletions
+209
View File
@@ -0,0 +1,209 @@
#!/usr/bin/env bash
# =============================================================================
# 从 deploy/backups/<时间戳>/ 恢复 Gitea 数据与 PostgreSQL
#
# ./scripts/restore.sh --list # 列出可用备份 + 校验状态
# ./scripts/restore.sh <时间戳> # dry-run: 只打印恢复计划
# sudo ./scripts/restore.sh <时间戳> --apply # 真正执行
#
# 选项(可与 --apply 组合):
# --db-only 只恢复数据库
# --data-only 只恢复数据目录
# --no-safety-backup 跳过"恢复前先备份当前状态"(不建议)
#
# 安全设计:
# * 默认 dry-run, 只有 --apply 才动手;
# * 先校验 SHA256SUMS, 任一文件不匹配立即中止;
# * 默认先跑一次 backup.sh --quiesce 保存当前状态, 恢复错了还能退回来;
# * 数据目录不做就地覆盖 —— 先把现有目录改名成 <dir>.pre-restore-<时间戳>,
# 再解包备份, 因此每一步都能手工回退(结尾会打印回退命令)。
# =============================================================================
set -euo pipefail
DEPLOY_DIR=$(cd "$(dirname "$0")/.." && pwd)
cd "$DEPLOY_DIR"
# ---------- 载入 .env(逐行, 不做 shell 展开; $$ 还原为 $)----------
[[ -f .env ]] || { echo "错误: 缺少 .env" >&2; exit 1; }
while IFS= read -r line || [[ -n "$line" ]]; do
[[ "$line" =~ ^[[:space:]]*(#|$) ]] && continue
key=${line%%=*}; val=${line#*=}
key=${key//[[:space:]]/}
[[ "$val" == \"*\" || "$val" == \'*\' ]] && val=${val:1:-1}
val=${val//\$\$/\$}
export "${key}=${val}"
done < .env
: "${POSTGRES_DB:?}"; : "${POSTGRES_USER:?}"; : "${GITEA_DATA_DIR:?}"
GITEA_UID=${GITEA_UID:-982}
GITEA_GID=${GITEA_GID:-982}
BACKUP_ROOT="${BACKUP_DIR:-$DEPLOY_DIR/backups}"
DUMP_NAME="postgres-${POSTGRES_DB}.dump"
# backup.sh 产出的【容器布局】数据包
DATA_NAME="gitea-data.tar.gz"
# 二进制部署时期的【宿主布局】数据包。顶层同样是 gitea/, 但内部是
# gitea/data/gitea-repositories/... 而容器要的是 gitea/git/repositories/...,
# 直接解到 GITEA_DATA_DIR 只会得到一份 Gitea 认不出的目录, 所以必须拒收。
SOURCE_DATA_NAME="gitea-source-data.tar.gz"
die() { echo "错误: $*" >&2; exit 1; }
step() { echo; echo "==> $*"; }
# ---------- 参数 ----------
MODE_LIST=0; APPLY=0; DO_DB=1; DO_DATA=1; SAFETY=1; STAMP=""
for a in "$@"; do
case "$a" in
--list) MODE_LIST=1 ;;
--apply) APPLY=1 ;;
--db-only) DO_DATA=0 ;;
--data-only) DO_DB=0 ;;
--no-safety-backup) SAFETY=0 ;;
-h|--help) sed -n '2,20p' "$0"; exit 0 ;;
-*) echo "未知参数: $a" >&2; exit 2 ;;
*) STAMP="$a" ;;
esac
done
list_backups() {
[[ -d "$BACKUP_ROOT" ]] || { echo "备份目录不存在: $BACKUP_ROOT"; return 0; }
printf '%-26s %-6s %-7s %-7s %s\n' "时间戳" "校验" "大小" "数据库" "数据目录"
local d name chk size db data
for d in "$BACKUP_ROOT"/*/; do
[[ -d "$d" ]] || continue
name=$(basename "$d")
if [[ -f "$d/SHA256SUMS" ]]; then
if (cd "$d" && sha256sum -c --status SHA256SUMS) 2>/dev/null; then chk="ok"; else chk="损坏"; fi
else
chk="-"
fi
size=$(du -sh "$d" 2>/dev/null | cut -f1)
if [[ -f "$d/$DUMP_NAME" ]]; then db="有"; else db="-"; fi
if [[ -f "$d/$DATA_NAME" ]]; then data="容器布局"
elif [[ -f "$d/$SOURCE_DATA_NAME" ]]; then data="宿主布局, 不可直接恢复"
else data="-"; fi
printf '%-26s %-6s %-7s %-7s %s\n' "$name" "$chk" "$size" "$db" "$data"
done
}
if [[ $MODE_LIST -eq 1 ]]; then
echo "备份目录: $BACKUP_ROOT"
echo
list_backups
exit 0
fi
if [[ -z "$STAMP" ]]; then
echo "已有一份备份清单如下 —— 请把时间戳作为参数传给本脚本。" >&2
echo >&2
list_backups >&2
exit 2
fi
SRC="$BACKUP_ROOT/$STAMP"
[[ -d "$SRC" ]] || die "找不到备份目录: $SRC"
[[ -f "$SRC/SHA256SUMS" ]] || die "缺少 $SRC/SHA256SUMS(无法校验完整性)"
[[ $DO_DB -eq 0 || -f "$SRC/$DUMP_NAME" ]] || die "缺少 $SRC/$DUMP_NAME"
if [[ $DO_DATA -eq 1 && ! -f "$SRC/$DATA_NAME" ]]; then
if [[ -f "$SRC/$SOURCE_DATA_NAME" ]]; then
cat >&2 <<EOF
错误: 该备份里的数据包是 $SOURCE_DATA_NAME —— 二进制部署时期的【宿主布局】备份
(内含 gitea/data/gitea-repositories/...), 与容器要求的 gitea/git/repositories/... 不同,
不能直接解到 $GITEA_DATA_DIR。
只想恢复数据库: 加 --db-only
想回滚到二进制: docker compose down && sudo systemctl start gitea(源数据仍在 /var/lib/gitea)
想要容器布局备份: ./scripts/backup.sh 生成一份新的
EOF
exit 1
fi
die "缺少 $SRC/$DATA_NAME"
fi
step "校验备份完整性"
(cd "$SRC" && sha256sum -c SHA256SUMS)
step "恢复计划"
cat <<EOF
来源 : $SRC
数据库 : $( [[ $DO_DB -eq 1 ]] && echo "$POSTGRES_DB <- $DUMP_NAME (pg_restore --clean --if-exists)" || echo "跳过" )
数据目录 : $( [[ $DO_DATA -eq 1 ]] && echo "$GITEA_DATA_DIR <- $DATA_NAME ($(du -h "$SRC/$DATA_NAME" | cut -f1))" || echo "跳过" )
恢复前备份 : $( [[ $SAFETY -eq 1 ]] && echo "会执行 ./scripts/backup.sh --quiesce" || echo "跳过(--no-safety-backup)" )
数据目录处理 : 现有目录改名 ${GITEA_DATA_DIR}.pre-restore-<时间戳> 后解包(不删除)
EOF
if [[ $APPLY -eq 0 ]]; then
echo
echo "==> 这是 dry-run, 未做任何改动。确认无误后加 --apply 执行。"
exit 0
fi
[[ $EUID -eq 0 ]] || die "--apply 需要 root(读写 $GITEA_DATA_DIR、chown、访问 docker)"
if [[ $SAFETY -eq 1 ]]; then
step "保存当前状态(恢复失败时的退路)"
./scripts/backup.sh --quiesce
fi
step "确保 db 容器在运行"
docker compose up -d db
DB_CID=$(docker compose ps -q db)
[[ -n "$DB_CID" ]] || die "拿不到 db 容器 id"
h=""
for _ in $(seq 1 24); do
h=$(docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{end}}' "$DB_CID" 2>/dev/null || echo "")
[[ "$h" == "healthy" ]] && break
sleep 5
done
[[ "$h" == "healthy" ]] || die "db 容器未变为 healthy(当前: ${h:-未知})"
echo " db: healthy"
step "停止 gitea 容器"
docker compose stop gitea
PRE="${GITEA_DATA_DIR}.pre-restore-$(date +%Y%m%d-%H%M%S)"
if [[ $DO_DATA -eq 1 ]]; then
step "恢复数据目录"
mv "$GITEA_DATA_DIR" "$PRE"
mkdir -p "$(dirname "$GITEA_DATA_DIR")"
tar -C "$(dirname "$GITEA_DATA_DIR")" -xzf "$SRC/$DATA_NAME"
chown -R "${GITEA_UID}:${GITEA_GID}" "$GITEA_DATA_DIR"
echo " 解包完成, 属主已设为 ${GITEA_UID}:${GITEA_GID}"
echo " 旧目录保留在: $PRE"
fi
if [[ $DO_DB -eq 1 ]]; then
step "恢复数据库 $POSTGRES_DB"
if docker compose exec -T db pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" \
--clean --if-exists --no-owner < "$SRC/$DUMP_NAME"; then
echo " pg_restore 完成"
else
echo " ⚠️ pg_restore 返回非 0 —— 请检查上面的输出。" >&2
echo " 常见无害项: 'does not exist, skipping'。仍以表数量与 verify.sh 为准。" >&2
fi
echo " public schema 表数量: $(docker compose exec -T db psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" \
-tAc "select count(*) from information_schema.tables where table_schema='public'")"
fi
step "启动 gitea"
docker compose up -d gitea
G_CID=$(docker compose ps -q gitea)
gh=""
for _ in $(seq 1 24); do
gh=$(docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{end}}' "$G_CID" 2>/dev/null || echo "")
[[ "$gh" == "healthy" ]] && break
sleep 5
done
echo " gitea: ${gh:-未知}"
step "验证"
./scripts/verify.sh || true
echo
echo "==> 恢复结束"
if [[ $DO_DATA -eq 1 ]]; then
echo "若数据目录恢复错了, 回退:"
echo " sudo docker compose stop gitea"
echo " sudo rm -rf '$GITEA_DATA_DIR' && sudo mv '$PRE' '$GITEA_DATA_DIR'"
echo " sudo docker compose start gitea"
fi