# Gitea + PostgreSQL(Docker Compose) 用 `docker compose` 运维 TJHLP 答疑平台的 Gitea 与 PostgreSQL。 本文档是唯一的部署与运维手册, 覆盖 **部署 / 备份 / 恢复 / 升级** 四条主流程。 ``` ┌──────────────────────────────────────────┐ 学生/助教 ──https──▶│ Apache httpd (宿主机, 已有) │ │ ProxyPass /QA → 127.0.0.1:2080 │ └───────────────┬──────────────────────────┘ │ 只绑回环 ┌───────────────▼──────────────────────────┐ │ docker compose 项目 "gitea" │ │ │ │ gitea (docker.gitea.com/gitea:1.27.3) │ │ │ /data ← ${GITEA_DATA_DIR} │ │ │ │ │ db (postgres:18.6 + zh_CN locale) │ │ /var/lib/postgresql │ │ ← ${POSTGRES_DATA_DIR} │ │ (PG18 实际数据在 18/docker/) │ └──────────────────────────────────────────┘ PostgreSQL 只在 compose 内部网络暴露, 不发布到宿主机 ``` --- ## 0. 快速索引 | 我要做什么 | 节 | 命令 | |---|---|---| | 在新主机上从零部署 | §4 | 见 §4 | | 看状态 / 日志 / 重启 | §8 | `docker compose ps` · `logs` | | **备份** | §5 | `sudo ./scripts/backup.sh --quiesce` | | **恢复**(含演练) | §6 | `sudo ./scripts/restore.sh <时间戳> --apply` | | **升级** Gitea / PostgreSQL | §7 | 备份 → 改 `.env` → `up -d` | | 改首页 / 中文术语 / 去 Gitea 化 | [`../customization/README.md`](../customization/README.md) | `python3 customization/build.py` → `docker compose restart gitea` | | main 推送后自动部署(方案) | [`ci-cd.md`](ci-cd.md) | Gitea Actions + 宿主 act_runner(host 模式) | | 出问题了 | §12 | — | | 退回二进制部署 | §9 | `docker compose down && sudo systemctl start gitea` | 三条铁律: 1. **任何升级 / 迁移 / 改动前先备份** —— `sudo ./scripts/backup.sh --quiesce`。 2. **没演练过的备份不算备份** —— 定期照 §6 在测试机上恢复一次。 3. **配置只改 `compose.yaml` 与 `.env`**, 不要手工编辑容器里的 `app.ini` (它是启动时按 env 生成的派生产物, 下次重建就被覆盖)。 --- ## 1. 关键设计决策 | 决策 | 理由 | |---|---| | 版本全部锁定 (`GITEA_VERSION`, `POSTGRES_VERSION`) | 可复现、升级/回滚是改一行 `.env` | | Gitea 只发布 `127.0.0.1:2080` | Apache 反代配置**无需改动**; 同时消除"直连 2080 绕过 TLS"的暴露面 | | PostgreSQL 不发布端口 | 只走 compose 内部网络; 外部无法直连数据库 | | 配置全部用 `GITEA__section__KEY` 环境变量 | 官方镜像支持的机制; 不把宿主绝对路径写进 `app.ini` | | 数据用 bind mount 而非 named volume | 备份/检查/回滚路径明确, 源数据可直接比对 | | 自建 `db` 镜像补 `zh_CN.UTF-8` | 官方 postgres 镜像只生成 `en_US.UTF-8`, 而现有集群 collation 是 `zh_CN.UTF-8` | | 关闭容器内 Gitea SSH | 现有部署的 git 用户没有 `.ssh/authorized_keys`, SSH 实际未使用 | | `db` 挂到 `/var/lib/postgresql`(而非 `.../data`) | postgres:18 把 `PGDATA` 改成 `/var/lib/postgresql/18/docker`, `VOLUME` 也上移了一层 | | 两个服务都 `restart: unless-stopped` | 开机自动恢复, 不依赖宿主的 gitea unit | --- ## 2. 已知陷阱(本机踩过的坑, 改配置前先读) > **⚠️ 1. postgres:18 的挂载点。** > 若沿用 18 之前的老写法把数据目录挂到 `/var/lib/postgresql/data`, 容器**不会启动**, > 入口脚本会打印 > `there appears to be PostgreSQL data in: /var/lib/postgresql/data (unused mount/volume)` > 然后 `exit 1` —— 它通过 `mountpoint` 加 `/proc/self/mountinfo` 把该路径判定为 > "未被使用的挂载点"。正确做法是挂父目录 `/var/lib/postgresql`, 数据落在 > `${POSTGRES_DATA_DIR}/18/docker`。这个新布局的用意是让将来 `pg_upgrade --link` > 不撞上挂载点边界。 > **⚠️ 2. s6 `setup` 的 chown 守卫 —— 会让 Gitea 以 `[F]` 崩溃。** > 镜像里的 `/etc/s6/gitea/setup` 以 **root** 身份、在 Gitea 启动之前运行: > ```bash > if [ ! -d /data/git/.ssh ]; then mkdir -p /data/git/.ssh; fi # ← 以 root 建 > chmod 700 /data/git/.ssh # ← 700 root:root > # only chown if current owner is not already the gitea ${USER}. No recursive check to save time > if ! [[ $(ls -ld /data/git | awk '{print $3}') = ${USER} ]]; then chown -R ${USER}:git /data/git; fi > ``` > 那个递归 chown 有守卫:**只有当 `/data/git` 的属主不是 `git` 时才执行**。如果 `/data/git` > 已经是 `git` 而里面某个文件(如刚被 root 建出来的 `.ssh`)是 `root:root`, 守卫为假 → > **递归 chown 被跳过** → `.ssh` 永久留在 `root:root 700`。Gitea 以 `git` 运行, 写不进去: > ``` > [F] gitea.dev/services/asymkey.RewriteAllPublicKeys(ctx) failed: > open /data/git/.ssh/authorized_keys.tmp: permission denied > ``` > 后果是容器 `Restarting` 死循环、`/api/healthz` 无响应、Apache `/QA` 返回 503。 > 同样的守卫也作用于 `/data/gitea`, 所以 `conf`、`log` 也可能变成 `root:root`。 > > **体检与修复**(迁移后 / 恢复后建议各跑一次): > ```bash > sudo docker compose exec -T gitea ls -ld /data/git /data/git/.ssh /data/gitea/conf /data/gitea/log > # 期望属主全是 git(git)。若出现 root: > sudo chown -R 982:982 /srv/gitea/git /srv/gitea/gitea/conf /srv/gitea/gitea/log > sudo docker compose restart gitea > ``` > **⚠️ 3. 定制覆盖层的文件权限 —— 又一次让 Gitea 以 `[F]` 崩溃。** > `customization/custom/*` 是**只读**挂载进容器的, 容器里 Gitea 以 `git`(982) 运行。 > 如果这些文件是 `600`(只读挂载不影响权限检查!), 启动时就报: > ```text > [F] processStartupTemplateError() Gitea can't run with template errors: > open home.tmpl: permission denied > ``` > 容器 `Restarting` 死循环。**预览环境不会暴露这个问题** —— 预览容器用 `PREVIEW_UID` > (默认宿主 uid 1001), 恰好就是文件属主, 所以 600 也读得到。 > ```bash > # 体检: 容器用户能否读到 > docker compose exec -T -u git gitea head -c1 /data/gitea/templates/home.tmpl > # 修复(会遍历 custom/ 补齐 g+r / o+r, 目录补 o+x) > python3 ../customization/build.py > python3 ../customization/build.py --check # 部署前也会校验, 不可读直接报错退出 > ``` > 编辑器/工具写文件常带 `600`; `git` 只记录可执行位, 所以**新克隆下来一般是 644**, > 偏偏本地改过的文件会中招。 > **⚠️ 4. 站点名 `APP_NAME` 只能用裸变量, `GITEA__DEFAULT__APP_NAME` **无效**。** > 镜像的 `/etc/s6/gitea/setup` 用 `envsubst` 渲染 `/etc/templates/app.ini`, 而模板第一行是 > `APP_NAME = $APP_NAME` —— 来源是**裸环境变量** `APP_NAME`。为什么 `GITEA__*` 那条路走不通: > `modules/setting/config_env.go` 会把段名小写化(`section = strings.ToLower(section)`), > 而 ini 库(`gopkg.in/ini.v1`)的默认段名常量是 `"DEFAULT"`(大写, 且默认区分大小写), > 所以 `GITEA__DEFAULT__X` 只会新建一个没用的 `[default]` 段, 顶层键纹丝不动。 > 症状: 页面标题变成 `Gitea: Git with a cup of tea`。 > > 而且模板**只在 `app.ini` 不存在时**渲染, 所以对已经生成过 `app.ini` 的部署, 光改 env > 不够, 必须让容器重新生成一次: > ```bash > sudo rm -f /srv/gitea/gitea/conf/app.ini > sudo docker compose up -d --force-recreate gitea > ``` > **⚠️ 5. 用 `curl` 验证本机服务时会被 HTTP 代理接管。** > 本机 shell 里设了 `http_proxy=127.0.0.1:7890`, 而 `no_proxy` 不覆盖 `127.0.0.1` 时, > 连 `curl http://127.0.0.1:2080/...` 都会走 mihomo, 而 **mihomo 对回环代理请求返回 > `502 Bad Gateway`**(响应头带 `Proxy-Connection: keep-alive`, 是代理在答而不是 Gitea)。 > 表现为"经 Apache 200、直连 502"的假故障。 > > 所有脚本(`verify.sh` / `restore.sh`)内部都已 `--noproxy '*'`; 手工验证时也要加: > ```bash > curl -sS --noproxy '*' http://127.0.0.1:2080/api/healthz > ``` > **⚠️ 6. compose 会把 shell 的 `http_proxy` 注入容器 —— 会让 OIDC 登录整条 404。** > `docker compose up` 会自动把**运行它的那个 shell** 里的 `HTTP_PROXY`/`HTTPS_PROXY`/ > `NO_PROXY`(大小写都算)注入容器。本机登录 shell 里是 > `http_proxy=http://localhost:7890`,而 **`localhost`/`127.0.0.1` 在容器里指向容器自己**, > 于是 Gitea 启动时拉 OIDC discovery 失败: > ```text > initOAuth2Sources() [E] Unable to register source: 高程统一身份认证 due to > Error: Failed to initialize OpenID Connect Provider ... proxyconnect tcp: > dial tcp 127.0.0.1:7890: connect: connection refused > ``` > 认证源注册不上 → 登录页的按钮还在(它来自数据库), 但点下去 > `/QA/user/oauth2/...` 返回 **404**, 统一身份认证**完全无法登录**。 > 这个坑很隐蔽: 容器是健康的、健康检查 `200`、登录页 `200`, 只有真正点登录才炸。 > > `compose.yaml` 现在**显式**给出这几个变量、且默认**空值**(= 容器内不用代理), > 显式赋值可以挡住自动注入。**默认不用代理的依据**(2026-09-13 实测): > * 容器**直连外网是通的**: `dl.gitea.com`、`api.github.com`、`codeload.github.com` > 在容器里直接 curl 分别是 `200/200/301`(`github.com` 主站直连会超时, 但平台不依赖它); > * 与功能相关的出站只有 OIDC, 目标是 `10.80.42.185`, 容器内直连即 `200`; > * 宿主 `7890` 那个代理是 **ssh 转发的开发用代理**, `ss -ltn` 显示只监听 > `127.0.0.1:7890`/`[::1]:7890` —— 在容器里 `127.0.0.1` 是容器自己, > `10.80.42.185:7890` 也不可达(实测 `curl -x` 直接 `Could not connect`), > 所以这个代理配进容器只会让出站先绕一圈再失败。 > > 将来真要给容器配代理, 必须是**容器可达**的地址(把隧道绑到 LAN 口, 或让容器用 > host 网络), 再在 `.env` 里给 `GITEA_HTTP_PROXY`(见 `.env.example`)。 > **每次 `up -d` 后建议验一次** OIDC 入口是否还通: > ```bash > curl -sS --noproxy '*' -o /dev/null -w '%{http_code} %{redirect_url}\n' \ > 'http://127.0.0.1:2080/user/oauth2/%E9%AB%98%E7%A8%8B%E7%BB%9F%E4%B8%80%E8%BA%AB%E4%BB%BD%E8%AE%A4%E8%AF%81' > # 期望: 307 + Location: http://10.80.42.185/oidc/auth?... (404 = 认证源没注册上) > ``` > > **⚠️ 7. 全新克隆 + compose: docker 会以 root 创建不存在的挂载源目录。** > `compose.yaml` 把 `customization/custom/{options,public,templates}` 逐个挂进容器。 > 其中 `options/` 里只有生成出来的 `locale_zh-CN.json`, 而它是 gitignore 的 —— 于是 > 全新克隆里这个目录不存在, **docker 会以 root 创建它**, 之后普通用户跑 > `customization/build.py` 就写不进去: > ``` > PermissionError: [Errno 13] Permission denied: .../custom/options/locale > ``` > 后果不是报错那么明显: 语言文件生成失败 → 中文界面退回上游文案(「工单」又回来了), > 而首页/登录页看起来一切正常。2026-09-13 第一次把生产切到部署克隆(CI 用的那份)时踩到。 > > 现在有两道防线: ①仓库里 `customization/custom/options/.gitkeep` 让目录随 checkout 就存在 > 且属于当前用户; ②`deploy/scripts/auto-deploy.sh` 在部署前检查三个目录存在且**可写**, > 不满足就明确报错。若已经中招: > ```bash > sudo rm -rf customization/custom/options # 空的 root 目录, 删掉即可 > ``` > > **⚠️ 8. act_runner 的 job 容器不要自己挂 `docker.sock`。** > act_runner 会把 docker daemon socket **自动**挂进 job 容器(`container.docker_host` 的默认 > 行为); 再在 `deploy/runner/config.yaml` 的 `container.options` 里挂一次, 第一次真实部署 > 就会以这个错误告终: > ``` > failed to create container: 'Duplicate mount point: /var/run/docker.sock' > ``` > 2026-09-13 用 `act_runner exec` 预演 job 时提前发现。`container.options` 里只保留 > 部署克隆(同路径)、宿主 docker CLI、compose 插件这三项。 > > **⚠️ 9. 宿主 `/usr/bin/python3` 是 3.6, 别让它排到 PATH 前面。** > `customization/build.py` 用了 `from __future__ import annotations`, 需要 ≥3.7。 > 宿主上正确的解释器是 `~/.local/bin/python3`(3.14), 但 `/usr/bin/python3` 是 Rocky 8 的 > 3.6 —— 只要 PATH 被改成 `/usr/bin` 优先, 就会看到 > `SyntaxError: future feature annotations is not defined`, 而且**语言文件静默地不再更新**。 > `auto-deploy.sh` 现在自己挑一个 ≥3.7 的解释器(并用它跑 build.py), 不依赖 PATH 顺序。 --- ## 3. 本机关键事实 | 项目 | 实测值 | |---|---| | 系统 / 架构 | Rocky Linux 8.10 / **aarch64** | | 对外地址 | `http://10.80.42.185/QA`(Apache `ProxyPass /QA http://localhost:2080`) | | 数据目录 | `/srv/gitea`(Gitea)、`/srv/pgdata/18/docker`(PG) | | git 用户 | uid/gid = **982:982**(容器内 `USER_UID`/`USER_GID` 必须对齐) | | 库属性 | `UTF8` / `zh_CN.UTF-8` | | 防火墙 | firewalld 已装但**未运行**; SELinux **Disabled** | | Docker | CE **29.8.0**(rhel/8 源), compose 插件 5.5.1 | > ⚠️ **Docker 源必须用 `linux/rhel/8`。** `linux/centos/8` 源在 CentOS 8 EOL 后已冻结在 > `docker-ce 26.1.3`(2024-04), 照抄 CentOS 教程会装到三年前的老引擎。 --- ## 4. 部署(全新主机) ### 4.1 前置条件 - Rocky Linux 8(aarch64), 有 `sudo` / root; - 宿主机已有 Apache 反代到 `127.0.0.1:2080`(本方案不改 Apache); - 规划好数据目录(默认 `/srv/gitea`、`/srv/pgdata`), 确保有空间。 ### 4.2 安装 Docker CE ```bash sudo dnf install -y dnf-plugins-core sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo sudo dnf install -y --allowerasing \ docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin sudo systemctl enable --now docker docker --version && docker compose version ``` **`--allowerasing` 是必需的, 不是可选项。** 首次按常规方式安装会失败: ``` package containerd.io-2.3.5-1.el8.aarch64 conflicts with runc provided by runc-4:1.2.9-6.module+el8.10.0+40310... package containerd.io-2.3.5-1.el8.aarch64 obsoletes runc provided by runc-4:1.2.9-6.module+el8.10.0+40310... package podman-4:4.9.4-37... requires runc >= 1.0.0-57, but none of the providers can be installed ``` 根因(已逐个版本核对 Docker 源的 `primary.xml`): Docker 源内**全部 30 个版本**的 `containerd.io` 都 `Obsoletes` + `Conflicts: runc`, 而 Rocky 8 的 `runc` 被 `containers-common`、`podman`、`buildah` 依赖。**所以这不是版本问题 —— 换老版本 Docker 一样冲突。Docker CE 与系统 podman 只能二选一。** `--allowerasing` 会由 `containerd.io` 取代 `runc`(它自带 runc 二进制), 连带移除 6 个包: `runc` `podman` `podman-catatonit` `buildah` `containers-common` `cockpit-podman`。 > 执行前先确认这些包没在承载东西: `podman ps -a` 为空、无镜像、无 Quadlet 单元, > `cockpit.socket` inactive + disabled。装完 docker-ce 后 podman 与 docker > **不能再共存**; 想要回 podman 必须先卸载 docker-ce。不接受移除的, 见附录 A。 ### 4.3 配置外网代理(dockerd **不**继承 shell 变量) 本机访问 docker.io 必须走代理(7890), 但 **`dockerd` 由 systemd 启动, 不会继承你 shell 里的 `http_proxy`/`https_proxy`** —— 所以 `curl` 能通、`docker build` 却报 `dial tcp ...: i/o timeout`。 雪上加霜的是本机对 `registry-1.docker.io` 的 **DNS 被污染**(实测解析到 `2a03:2800:f10f:83:face:b00c:...`, Facebook 地址段), 直连必然超时; 走 HTTP 代理时由代理 负责解析域名, 反而正常: | 目标 | 直连 | 经代理 `127.0.0.1:7890` | |---|---|---| | `registry-1.docker.io` | `000`(15s 超时) | `401`(0.9s, 正常响应) | | `docker.gitea.com` | `200` | `200` | 代理要配到**三个互相独立**的地方, 缺一个就有一类操作不生效: | 层 | 文件 | 作用 | |---|---|---| | `dockerd` | `/etc/systemd/system/docker.service.d/http-proxy.conf` | 镜像拉取 | | `containerd` | `/etc/systemd/system/containerd.service.d/http-proxy.conf` | 兜底 | | CLI / BuildKit | `~/.docker/config.json` 的 `proxies` 段 | 自动给 `RUN` 步骤注入代理参数 | ```bash # 1) dockerd sudo mkdir -p /etc/systemd/system/docker.service.d sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf >/dev/null <<'EOF' [Service] Environment="HTTP_PROXY=http://127.0.0.1:7890" Environment="HTTPS_PROXY=http://127.0.0.1:7890" Environment="NO_PROXY=localhost,127.0.0.1,::1,.local,.internal" EOF # 2) containerd sudo mkdir -p /etc/systemd/system/containerd.service.d sudo tee /etc/systemd/system/containerd.service.d/http-proxy.conf >/dev/null <<'EOF' [Service] Environment="HTTP_PROXY=http://127.0.0.1:7890" Environment="HTTPS_PROXY=http://127.0.0.1:7890" Environment="NO_PROXY=localhost,127.0.0.1,::1" EOF sudo systemctl daemon-reload sudo systemctl restart containerd docker # 3) CLI / BuildKit(当前用户; 用 sudo 跑 docker 时也要给 root 配一份) mkdir -p ~/.docker cat > ~/.docker/config.json <<'EOF' { "proxies": { "default": { "httpProxy": "http://127.0.0.1:7890", "httpsProxy": "http://127.0.0.1:7890", "noProxy": "localhost,127.0.0.1,::1" } } } EOF sudo cp ~/.docker/config.json /root/.docker/config.json 2>/dev/null || true # 端到端验证 docker pull hello-world ``` > **已知坑: BuildKit 解析 `FROM` 时不走这个代理。** > `docker pull postgres:18.6` 走 dockerd 自己的 registry 客户端, 会遵守上面的 drop-in; > 但 `docker compose build` 里 `[internal] load metadata` 那一步是 **BuildKit** 在解析 > `FROM docker.io/library/postgres:18.6`, 它会**绕过代理直连**, 对 `auth.docker.io` > 做本地 DNS 查询(报 `lookup auth.docker.io on 202.120.190.208:53: i/o timeout`)。 > 本机没有独立 `buildkitd`、没有自定义 builder、没有 `daemon.json`, BuildKit 内嵌在 > dockerd 里 —— 也就是说代理变量在场却未被采用, 属 BuildKit 解析器的行为, 不是配置写错。 > > **规避办法: 先用 `docker pull` 把基础镜像拉到本地**(见 4.5), 之后 BuildKit 直接命中 > 本地镜像, 不再访问 registry。 > 还有**第四件事**: 容器内部的代理(例如让 Gitea 去拉外部头像 / 发外部 webhook)。 > 那是 compose `environment:` 的事。当前 `GITEA_OFFLINE_MODE=true`, 暂不需要。 ### 4.4 配置 `.env` ```bash cd /home/ymy/tjhlp-gitea/deploy cp .env.example .env $EDITOR .env ``` 必须有值的键(其余有默认值): | 键 | 说明 | |---|---| | `GITEA_ROOT_URL` / `GITEA_DOMAIN` | 必须与 Apache 反代一致, 否则克隆地址与链接会错 | | `GITEA_HTTP_PORT` | 必须等于 Apache `ProxyPass` 的目标端口(本机 `2080`) | | `GITEA_APP_NAME` | 站点名, 走**裸变量**(陷阱 3) | | `GITEA_DATA_DIR` / `POSTGRES_DATA_DIR` | 数据落盘位置 | | `GITEA_UID` / `GITEA_GID` | 必须等于数据目录属主(本机 `982:982`) | | `POSTGRES_DB` / `POSTGRES_USER` / `POSTGRES_PASSWORD` | 数据库 | | `GITEA_INTERNAL_TOKEN` / `GITEA_LFS_JWT_SECRET` / `GITEA_OAUTH2_JWT_SECRET` | 密钥, 生成见下 | | `GITEA_SECRET_KEY` | 见 §11; 留空 = 用 Gitea 内置默认值 | ```bash # 生成密钥 docker run --rm docker.gitea.com/gitea:1.27.3 gitea generate secret INTERNAL_TOKEN docker run --rm docker.gitea.com/gitea:1.27.3 gitea generate secret LFS_JWT_SECRET docker run --rm docker.gitea.com/gitea:1.27.3 gitea generate secret JWT_SECRET # -> OAUTH2_JWT_SECRET docker run --rm docker.gitea.com/gitea:1.27.3 gitea generate secret SECRET_KEY ``` **校验配置**(取代了早先的 `preflight.sh`; 只读, 不需要 daemon): ```bash docker compose config --quiet && echo "compose 插值 OK" docker compose config | grep -E 'APP_NAME|ALLOWED_HOST|image:' # 抽查关键项 ``` ### 4.5 启动 ```bash cd /home/ymy/tjhlp-gitea/deploy # ★ 先预拉基础镜像, 绕开 BuildKit 的 FROM 解析(见 4.3) docker pull docker.io/library/postgres:18.6 docker pull docker.gitea.com/gitea:1.27.3 docker compose up -d --build docker compose ps ``` 首次启动 `db` 会 `initdb`(`UTF8` + `zh_CN.UTF-8`), `gitea` 会自动建表。 ### 4.6 验证 ```bash sudo ./scripts/verify.sh ``` 检查: 两个容器 `healthy`、`/api/healthz` 200、`/api/v1/version` 版本正确、经 Apache `/QA` 200。 站点名与登录源可以单独确认: ```bash curl -sS --noproxy '*' http://127.0.0.1:2080/user/login | grep -o '[^<]*' # 期望: Sign In - 你的站点名 ``` locale 是否真的生效: ```bash docker compose exec -T db psql -U gitea -d giteadb -tAc \ "select datname, pg_encoding_to_char(encoding), datcollate from pg_database where datname='giteadb'" # 期望: giteadb | UTF8 | zh_CN.UTF-8 ``` ### 4.7 收尾 **若是从宿主二进制部署迁移过来的, 必须停用宿主 unit。** 否则重启后宿主 gitea 与容器会抢 `127.0.0.1:2080` —— 两边都会开机自启(`docker.service` enabled, 容器 `restart: unless-stopped`), 谁先 bind 谁赢。若宿主赢了, 平台会**静默地**退回旧库运行: 容器起不来, 但 Apache `/QA` 依然返回 200, 从外部**完全看不出来**。 ```bash sudo systemctl disable gitea # 容器侧开机会自己回来, 不需要宿主 unit ``` **要不要把用户加进 `docker` 组?** 加了确实方便 —— `docker` 命令不用 `sudo`, `verify.sh` / `backup.sh` / `restore.sh` 都能直接跑。但这是一次实打实的权限降级: - **`docker` 组等价于免密 root。** 组内用户可以 `docker run -v /:/host -it alpine chroot /host` 直接拿到宿主 root shell。 Docker 官方文档同样说明 *"The docker group grants root-level privileges to the user"* ()。 - **`wheel` 与 `docker` 组的区别就在密码。** 已加入 `wheel` 的话 `sudo` **需要输密码**; `docker` 组**不需要**。一旦有人拿到一个 `ymy` 的 shell(SSH 会话劫持、被投毒的脚本或依赖、 code-server 会话), `wheel` 还挡着一道密码, `docker` 组则直接就是 root。 - **这台机器是共享的。** Apache/PHP 对整个平台提供 Web 服务, 还跑着 MySQL、Redis、 code-server。root 沦陷的爆炸半径是整台机器, 不只是 Gitea。 **建议: 不加, 继续用 `sudo`。** 日常 docker 命令用得很少 —— `restart: unless-stopped` 让容器开机自动拉起, 平时只有偶尔看日志/升级/备份, `sudo` 的开销基本可忽略。 若确实想要免密, 比进 `docker` 组**更安全**的做法是给一个只放行固定动作的 wrapper + sudoers 规则(**不能**直接放行裸 `docker`, 那等于没限制): ```bash # /usr/local/sbin/gitea-ctl —— 只暴露固定动作 #!/usr/bin/env bash cd /home/ymy/tjhlp-gitea/deploy || exit 1 case "${1:-}" in up) exec docker compose up -d ;; down) exec docker compose down ;; ps) exec docker compose ps ;; logs) shift; exec docker compose logs --tail=200 "$@" ;; verify) exec ./scripts/verify.sh ;; backup) exec ./scripts/backup.sh --quiesce ;; *) echo "用法: gitea-ctl {up|down|ps|logs|verify|backup}" >&2; exit 1 ;; esac ``` ``` # /etc/sudoers.d/gitea-ctl (先用 visudo -f 校验再生效) ymy ALL=(root) NOPASSWD: /usr/local/sbin/gitea-ctl ``` --- ## 5. 备份 ```bash cd /home/ymy/tjhlp-gitea/deploy sudo ./scripts/backup.sh # 在线备份(不中断服务) sudo ./scripts/backup.sh --quiesce # 先停 gitea 再备份, 一致快照(推荐) ``` **必须用 root 跑**: 打包 `GITEA_DATA_DIR` 时要读取 `.ssh` 等 `700` 目录, 并且要保留文件属主。 产物在 `deploy/backups/<时间戳>/`: | 文件 | 内容 | |---|---| | `postgres-.dump` | `pg_dump -Fc` 自定义格式, 用 `pg_restore` 恢复 | | `gitea-data.tar.gz` | `GITEA_DATA_DIR` 全量打包(**容器布局**) | | `MANIFEST.txt` | 时间/主机/镜像/大小 | | `SHA256SUMS` | 校验和, `restore.sh` 恢复前会验证 | `--quiesce` 与在线备份的区别: 在线备份时 Gitea 仍在写库/写仓库, 两份产物之间存在时间差, 极端情况下恢复出来的"库"与"仓库"不一致。**做重要节点(升级前、迁移前)一律用 `--quiesce`。** **定期备份**(root 的 crontab, 每天 03:00 一致快照): ```bash sudo crontab -e # 0 3 * * * cd /home/ymy/tjhlp-gitea/deploy && ./scripts/backup.sh --quiesce >> /var/log/gitea-backup.log 2>&1 ``` **保留策略**: 备份目录不会被自动清理, 需要自己 prune(数据只有几 MB, 但 `pg_dump` 有 40 MB 上下)。建议保留最近 7 份 + 每月 1 份, 并**异地留一份** —— 同一块盘上的备份挡不住盘坏。 可以改 `BACKUP_DIR` 指向外部挂载点。 > ⚠️ `backup.sh` 产出的是**容器布局**的数据包。历史遗留的 > `deploy/backups/pre-migration-*/gitea-source-data.tar.gz` 是二进制部署时期的**宿主布局** > (`gitea/data/gitea-repositories/...`), **不能**用 `restore.sh` 恢复数据目录(脚本会拒收)。 > 那些备份只有 `postgres-giteadb.dump` 还能用(`--db-only`)。 --- ## 6. 恢复 ```bash cd /home/ymy/tjhlp-gitea/deploy # 1) 看有哪些备份, 以及校验状态(不需要 root) ./scripts/restore.sh --list # 2) dry-run: 校验校验和 + 打印恢复计划, 不动任何东西 ./scripts/restore.sh 20260912-030000 # 3) 真正执行 sudo ./scripts/restore.sh 20260912-030000 --apply ``` 选项: | 选项 | 作用 | |---|---| | `--db-only` | 只恢复数据库(数据目录不动) | | `--data-only` | 只恢复数据目录(库不动) | | `--no-safety-backup` | 跳过"恢复前先备份当前状态"(不建议) | `--apply` 的执行顺序: 1. **校验 `SHA256SUMS`** —— 任一文件不匹配立即中止; 2. 跑一次 `backup.sh --quiesce`, 把**当前**状态存下来(恢复错了还能退回去); 3. `docker compose up -d db` 并等 `healthy`; 4. `docker compose stop gitea`; 5. 数据目录: **先把现有目录改名**成 `${GITEA_DATA_DIR}.pre-restore-<时间戳>`(不删除), 再解包备份, 然后 `chown -R 982:982`; 6. 数据库: `pg_restore --clean --if-exists --no-owner`, 并打印恢复后的表数量; 7. `docker compose up -d gitea`, 等 `healthy`, 跑 `verify.sh`; 8. 打印数据目录的回退命令。 脚本失败或恢复错了, 按它打印的命令回退: ```bash sudo docker compose stop gitea sudo rm -rf /srv/gitea && sudo mv /srv/gitea.pre-restore-<时间戳> /srv/gitea sudo docker compose start gitea ``` **手工等价的恢复命令**(脚本不可用时): ```bash sudo docker compose stop gitea docker compose exec -T db pg_restore -U gitea -d giteadb --clean --if-exists --no-owner \ < backups/<时间戳>/postgres-giteadb.dump sudo mv /srv/gitea /srv/gitea.bak && sudo tar -C /srv -xzf backups/<时间戳>/gitea-data.tar.gz sudo chown -R 982:982 /srv/gitea sudo docker compose up -d ``` > **演练建议**: 至少每学期做一次 —— 在测试机上把最新备份 `--apply` 一遍, 确认站点能起来、 > 仓库能 clone、Issue 都在。备份坏了通常是恢复的那一刻才发现。 恢复后若 Gitea 报 `[F] ... permission denied`, 见陷阱 2 的体检命令。 --- ## 7. 升级 > **第一步永远是备份。** Gitea 的数据库迁移不可逆 —— 升级后想退回旧镜像, 旧版本很可能 > 因为 schema 版本比它新而拒绝启动, 唯一退路就是备份。 ### 7.1 升级 Gitea ```bash cd /home/ymy/tjhlp-gitea/deploy # 1) 备份(必做) sudo ./scripts/backup.sh --quiesce # 2) 读 release notes, 确认没有 breaking change # https://github.com/go-gitea/gitea/releases # 3) 改版本 sed -i 's/^GITEA_VERSION=.*/GITEA_VERSION=1.28.0/' .env # 或 $EDITOR .env # 4) 同步定制基线: 拉上游快照 → 合并模板改动 → 重新生成语言文件 # (详见 ../customization/README.md; build.py 会因「覆盖的键不存在」而报错, # 把上游改键名/删键的风险挡在部署之前) ../customization/fetch-upstream.sh 1.28.0 # 手动 diff upstream/ 并更新 customization/custom/templates/*.tmpl python3 ../customization/build.py --check # 5) 拉取并重建 docker compose pull gitea docker compose up -d gitea # 6) 看迁移日志 + 验证 docker compose logs --since 5m gitea | grep -iE 'migrat|error|\[F\]' sudo ./scripts/verify.sh curl -s http://10.80.42.185/QA/ | grep -c 课程答疑平台 # 抽查定制仍在生效 ``` **回滚**: 把 `GITEA_VERSION` 改回旧值 → `docker compose up -d gitea`。 若旧版本因 schema 更新而拒绝启动, 用 §6 恢复升级前的备份。 ### 7.2 升级 PostgreSQL **小版本(18.6 → 18.7): 可以直接改**, PG 保证 minor 版本 on-disk 兼容。 ```bash sudo ./scripts/backup.sh --quiesce sed -i 's/^POSTGRES_VERSION=.*/POSTGRES_VERSION=18.7/' .env docker compose up -d --build db # POSTGRES_VERSION 是 build arg, 要重建镜像 sudo ./scripts/verify.sh ``` **大版本(18 → 19): 不能只改版本号。** 数据目录布局与 on-disk 格式都不兼容, 必须把数据 导出再导入。因为 `pg_dump` 的产物跨大版本可读, 这条路最稳: ```bash cd /home/ymy/tjhlp-gitea/deploy sudo ./scripts/backup.sh --quiesce # 得到 postgres-giteadb.dump docker compose down sudo mv /srv/pgdata /srv/pgdata.pg18 # 保留旧集群, 不删 sed -i 's/^POSTGRES_VERSION=.*/POSTGRES_VERSION=19.0/' .env docker compose up -d --build db # 用新版本 initdb(仍带 zh_CN.UTF-8) # 灌回数据 docker compose exec -T db pg_restore -U gitea -d giteadb --clean --if-exists --no-owner \ < backups/<时间戳>/postgres-giteadb.dump docker compose up -d gitea sudo ./scripts/verify.sh ``` > ⚠️ 大版本升级会换掉 `PGDATA` 的路径层级(`/var/lib/postgresql//docker`), 所以 > `POSTGRES_DATA_DIR` 本身不用改, 但**旧目录一定要先改名保留**, 确认新集群没问题再删。 > 另外 `pg_restore` 用的 `pg_restore` 二进制应来自**新版本**容器(本方案是在容器内执行, > 天然满足)。 ### 7.3 升级检查单 - [ ] 已 `backup.sh --quiesce`, 且 `restore.sh --list` 显示校验 `ok` - [ ] 读过 release notes, 确认没有 breaking change(配置文件段位变更、弃用项) - [ ] 避开发答疑高峰, 预留 30 分钟 - [ ] 升级后 `verify.sh` 全绿 - [ ] 升级后日志无 `[F]` / `[E]` - [ ] 登录一次, 确认 OIDC 登录源与仓库 clone 正常 - [ ] 确认无误后再清理旧备份 / 旧数据目录 --- ## 8. 日常运维 ```bash cd /home/ymy/tjhlp-gitea/deploy docker compose ps # 状态(含 health) docker compose logs -f --tail=100 gitea docker compose restart gitea sudo ./scripts/verify.sh # 完整体检 docker compose exec -T db psql -U gitea -d giteadb # 进库 ``` 改了 `compose.yaml` 或 `.env` 之后: ```bash docker compose up -d # 增量生效(必要时 --force-recreate) ``` 改了**只由模板渲染**的键(如 `GITEA_APP_NAME`)则要重建 `app.ini`, 见陷阱 3。 --- ## 9. 回滚 **回滚到宿主二进制部署**(源数据与源库都还在原地, 迁移只复制不移动): ```bash cd /home/ymy/tjhlp-gitea/deploy docker compose down sudo systemctl enable --now gitea # 之前 disable 过, 这里要 enable 回来 ``` 源数据 `/var/lib/gitea` 与源库 `giteadb` 未被修改, 立即恢复原状。 **回滚一次升级**: 见 §7 各小节。 --- ## 10. 外部依赖: OAuth2/OIDC 登录源(`高程统一身份认证`) 库里有一条 `login_source` 记录(id=1), 指向 `http://10.80.42.185/oidc/.well-known/openid-configuration`。**这个服务的可用性不影响 Gitea 本身**, 只影响该登录源能否注册。两类日志要分清: | 日志 | 级别 | 含义 | |---|---|---| | `Failed to create OpenID Connect Provider ... Non-success code for Discovery URL: 503` | `[W]`/`[E]` | **不致命**。Gitea 跳过该源, 其余功能正常; 页面不显示该登录按钮 | | `asymkey.RewriteAllPublicKeys ... permission denied` | `[F]` | **致命**。进程退出, 容器重启循环(见陷阱 2) | Gitea 只在**启动时**注册 OAuth2 源(`initOAuth2Sources()`), 所以: > **IdP 恢复后, 必须重启 gitea 容器, 登录源才会被重新注册。** > `sudo docker compose restart gitea` IdP 侧改动后的验证步骤(从外到内, 任一步失败都会表现为同一个 503): ```bash cd /home/ymy/tjhlp-gitea/deploy # 1. 宿主机上能不能拿到 discovery 文档(走 Apache -> /oidc) curl -sS --noproxy '*' -o /dev/null -w 'host -> %{http_code}\n' \ http://10.80.42.185/oidc/.well-known/openid-configuration # 2. 容器内能不能拿到(网络路径不同, 这一条才是 Gitea 真正走的) sudo docker compose exec -T gitea curl -s -o /dev/null -w 'cont -> %{http_code}\n' \ http://10.80.42.185/oidc/.well-known/openid-configuration # 3. 重启后确认不再有注册失败 sudo docker compose restart gitea sudo docker compose logs --since 2m gitea | grep -i 'register source' || echo "OK: 无注册失败" # 4. 登录页上该登录源是否出现(应为 1 或更大) curl -sS --noproxy '*' http://127.0.0.1:2080/user/login | grep -c '高程统一身份认证' # 5. 库里的记录本身还在(与 IdP 无关, 只是确认没丢这条配置) sudo docker compose exec -T db psql -U gitea -d giteadb -tAc \ "select id,name,is_active from login_source" ``` 第 1 步通、第 2 步不通, 通常是容器到宿主机 IP 的可达性问题(而不是 IdP 的问题); 两步都 503 才是 IdP 侧还没起来。第 4 步为 `0` 说明源仍未注册成功。 --- ## 11. `SECRET_KEY` 与安全 Gitea 源码 `modules/setting/security.go`: ```go SecretKey = loadSecret(sec, "SECRET_KEY_URI", "SECRET_KEY") if SecretKey == "" { // FIXME: ... Until it supports rotating an existing secret key, // we shouldn't move users off of the widely used default value SecretKey = "!#@FDEWREWR&*(" } ``` 也就是说: 本实例一直在用这个**公开的内置常量**。官方文档对 `SECRET_KEY` 的说明是 "if you lost it, the data encrypted by it (like 2FA secret) can't be decrypted anymore"。 本实例的受影响面很小(已核对): `two_factor = 0`, `webauthn_credential = 0`, 唯一的加密相关对象是 1 个 OAuth2 登录源「高程统一身份认证」。 - **默认**: `.env` 里 `GITEA_SECRET_KEY` 留空 → 沿用同一默认值, **行为完全不变**, SSO 不受影响。 - **加固(可选, 需单独安排窗口)**: 生成随机 `SECRET_KEY` 写入 `.env` → `docker compose up -d gitea` → 到管理后台**重新填写 OIDC 登录源的 Client Secret** (这会让它用新密钥重新加密) → 验证 SSO 登录。**跳过重配会导致 OIDC 登录失败。** 其它安全要点: - PostgreSQL 不能发布端口到宿主机; Gitea 只发布回环(见 §1)。 - `.env` 含密钥, 已被 `.gitignore` 排除, **不要提交**。 - `.env` 值里含 `$` 要写成 `$$`(compose 会做变量插值); 含 `#` 或空格要用引号。 --- ## 12. 故障排查速查 | 症状 | 先看 | 处置 | |---|---|---| | 容器 `Restarting` 死循环, `/api/healthz` 不通 | `docker compose logs gitea \| grep '\[F\]'` | `permission denied` → 陷阱 2 | | 页面标题是 `Gitea: Git with a cup of tea` | §2 陷阱 3 | 删 `app.ini` 重建 | | `db` 容器起不来, 日志提 `unused mount/volume` | §2 陷阱 1 | 挂载点应为 `/var/lib/postgresql` | | `curl 127.0.0.1:2080` 返回 502 | §2 陷阱 4 | 加 `--noproxy '*'` | | 登录页没有 `高程统一身份认证` | §10 | 确认 IdP 可达后 `restart gitea` | | 重启后平台"正常但数据是旧的" | — | 宿主 `gitea.service` 抢了 2080, 见 §4.7 | | `docker build` 报 `lookup auth.docker.io ... i/o timeout` | §4.3 | 先 `docker pull` 基础镜像 | | `docker pull` 报 `i/o timeout` | §4.3 | 代理 drop-in 没生效, `systemctl show docker -p Environment` | | 容器 healthy 但站点 503 | `docker compose logs gitea` | 多为 `.env` 里 DB 密码与既有数据不一致 | --- ## 13. 附录 A: RPM 冲突的三条路线 因为 `containerd.io` 与发行版 `runc` 互斥(§4.2), 本机只有三种选择: | 路线 | 系统改动 | 代价 | |---|---|---| | **A. Docker + `--allowerasing`**(已采用) | 移除 `runc/podman/podman-catatonit/buildah/containers-common/cockpit-podman` | 与 podman 二选一; 得到 dnf 托管的 Docker CE 29.8.0 | | **B. 保留 podman, 用 Docker 静态二进制** | 不动任何 RPM, 只往 `/usr/local/bin` 放文件 | 不受 dnf 管理: 升级手工做, systemd unit 自己维护 | | **C. 放弃 Docker, 纯 Podman** | 零改动 | 需额外 compose provider; `depends_on: service_healthy` 语义弱, 可能要改写 Quadlet | ### B. Docker 静态二进制(保留 podman) ```bash curl -fsSLo /tmp/docker.tgz https://download.docker.com/linux/static/stable/aarch64/docker-29.8.0.tgz tar -C /usr/local --strip-components=1 -xzf /tmp/docker.tgz # dockerd/containerd/runc/docker... mkdir -p /usr/local/lib/docker/cli-plugins curl -fsSLo /usr/local/lib/docker/cli-plugins/docker-compose \ https://github.com/docker/compose/releases/latest/download/docker-compose-linux-aarch64 chmod +x /usr/local/lib/docker/cli-plugins/docker-compose ``` 静态包自带 `runc`/`containerd`, 不碰 RPM 数据库, 因此与 podman 无冲突; 但需要自备 systemd unit(`Type=notify`, `ExecStart=/usr/local/bin/dockerd`)。 ### C. 纯 Podman ```bash sudo dnf install -y podman-compose # 或用 Go 版 docker-compose 二进制作 provider podman compose up -d ``` 注意: - rootless 容器要开机自启/登出后存活, 需要 `sudo loginctl enable-linger `; - 本机 Podman 网络后端是较老的 **CNI**; 若将来启用 firewalld, `firewall-cmd --reload` 可能清掉 Podman 规则, 需要 `podman network reload`; - 换哪条路线, 容器发布的回环端口都不变, Apache 依旧不用改。 --- ## 14. 附录 B: 二进制 → 容器迁移(已完成, 仅存档) 本机原有部署是 **Gitea 1.27.3 二进制 + systemd + 宿主 PostgreSQL 18.6** (`ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini`, 监听 `0.0.0.0:2080`)。 迁移已于 2026-09-11 完成, 当时用的一次性脚本(`migrate-from-binary.sh` / `install-docker.sh` / `configure-docker-proxy.sh` / `preflight.sh`)已按"一次性"清理掉, 过程留档如下。 **做法**: `systemctl stop gitea` → `rsync` 复制数据(**复制, 不移动**)→ `docker compose up -d --build db` 建新集群 → `pg_restore` 灌库并核对表数量 → `up -d gitea` → 验证。源数据与源库全程未改, 因此回滚只需 `docker compose down && systemctl start gitea`(§9)。 **当时的迁移前备份**: `deploy/backups/pre-migration-*/`(7 份, 每份含 `postgres-giteadb.dump` + `gitea-source-data.tar.gz`)。注意数据包是**宿主布局**, 只能 `restore.sh --db-only` 用, 见 §5 的警告。 ### 与宿主 `app.ini` 的**有意**差异 除"路径改为容器语义"外, 以下是有意为之的行为变化: | 配置 | 迁移前 | 现在 | 原因 | |---|---|---|---| | `log.MODE` | `file` | `console` | 日志进 stdout, 用 `docker compose logs` 收集 | | `server.DISABLE_SSH` | `false` | `true` | 实测 `/home/git/.ssh` 不存在, SSH 从未使用; 避免暴露无法工作的克隆地址 | | `server.DOMAIN` | `localhost` | 实际主机/IP | `localhost` 会生成错误的克隆地址; `ROOT_URL` 已显式指定, 此项属修正 | | `security.ALLOWED_HOST_LIST` | `[security]`(**正确**) | **保持 `[security]`** | 1.27 的规范位置就是 `[security]`; `[webhook]` 是 v28.0.0 将移除的 deprecated fallback | | `server.HTTP_ADDR` | `0.0.0.0:2080` | 容器内 `0.0.0.0`, 宿主只发布 `127.0.0.1:2080` | 保持 Apache 反代路径不变, 同时消除直连暴露面 | | `oauth2.ENABLED` | 未设置(默认 `true`) | 显式 `true` | 防止上游改默认值导致漂移 | 其余配置(注册策略、OIDC 自动注册、admin 限制、pull-request/signing 默认值、 `PASSWORD_HASH_ALGO=pbkdf2`、`OFFLINE_MODE`、webhook TLS 等)均按原值 1:1 保留。 **迁移中发现并处理的既有问题**: | # | 问题 | 证据 | 处理 | |---|---|---|---| | 1 | 未设置 `SECRET_KEY` | `/etc/gitea/app.ini` 无该键 | 保持默认, 见 §11 | | 2 | 监听 `0.0.0.0:2080` | `ss -ltn` 显示 `*:2080`; firewalld 未运行 | 容器只发布 `127.0.0.1:2080` | | 3 | `/oidc` 反代指向死端口 | `httpd.conf` 里 `ProxyPass /oidc http://localhost:3000/oidc`, 而 3000 无监听 | IdP 侧问题, 见 §10 | | 4 | 数据目录里留着 amd64 包 | `/var/lib/gitea/gitea-1.26.1-linux-amd64.xz`(本机是 arm64) | 新数据目录不含它 | --- ## 15. 文件清单 ``` deploy/ ├── README.md 本文档(部署 / 备份 / 恢复 / 升级) ├── compose.yaml 服务定义(版本锁定 / 回环发布 / 环境变量注入配置) ├── .env.example 配置模板(复制为 .env) ├── db/Dockerfile postgres + zh_CN.UTF-8 locale(版本由 build arg 传入) ├── backups/ 备份产物(.gitignore 排除) └── scripts/ ├── backup.sh 备份: pg_dump + 数据 tar + SHA256SUMS ├── restore.sh 恢复: 默认 dry-run, 校验校验和后按备份还原 └── verify.sh 体检: 容器健康 + 回环 API + 经 Apache 反代 ``` 常用命令: ```bash cd /home/ymy/tjhlp-gitea/deploy docker compose config --quiet # 校验 compose 与 .env 插值 docker compose up -d --build # 启动 / 应用配置变更 docker compose ps && docker compose logs -f --tail=100 gitea sudo ./scripts/verify.sh # 体检 sudo ./scripts/backup.sh --quiesce # 备份 ./scripts/restore.sh --list # 看备份 sudo ./scripts/restore.sh <时间戳> --apply # 恢复 ``` --- ## 16. 验证状态(诚实声明) ### 已在本机实测通过(2026-09-11, Rocky 8.10 aarch64) - Docker CE 29.8.0 安装(路线 A, `--allowerasing`, podman/runc 已移除); - `docker.service` / `containerd.service` 的代理 drop-in 生效; - `db` 镜像构建成功(`local/gitea-postgres:18.6-zh_CN`); - `db` 容器 `healthy`, `initdb` 带 `--locale=zh_CN.UTF-8` 完成; - `pg_restore` 端到端跑通: **源 116 张表 → 目标 116 张表**; - Gitea 容器 `healthy`, `/api/healthz` 200, `/api/v1/version` = 1.27.3; - 经 Apache `/QA` 反代 200(与迁移前路径一致); - 站点名正确渲染: `Sign In - 同济高程-答疑平台`; - OAuth2/OIDC 登录源 `高程统一身份认证` 注册成功(discovery 200, 登录页出现); - 失败自动回滚(迁移脚本的 EXIT trap)三次实测生效。 ### 本机踩到并已修复的坑 见 §2 的四个陷阱(postgres:18 挂载点、s6 chown 守卫、`APP_NAME`、代理回环 502), 以及验证脚本自身的三个缺陷: 回环探测被 HTTP 代理接管、启动竞态被误报为 FAIL、 状态码拼接成 `502000`。 ### 仍未实测 - `restore.sh --apply` 的完整演练(**只验证了 `--list` 与 dry-run 路径**)—— 建议尽快照 §6 在测试机上真跑一遍; - `backup.sh` 的 cron 定时执行; - `environment-to-ini` 对含点号 section(如 `GITEA__cron.update_checker__ENABLED`) 的处理 —— `conf/app.ini` 已生成且实例工作正常, 但未逐项比对; - PostgreSQL 大版本升级流程(§7.2)—— 步骤按官方文档与 PG18 布局推导, 未实跑; - 重启后"容器自动恢复 + 宿主 unit 已 disable"的组合(建议找时间 `sudo reboot` 验一次)。