Files
tjhlp-gitea/deploy/README.md
T
admin 25f1ec6cfc fix: 固定容器出站代理(修复 OIDC 登录 404); 并关闭通行密钥
1) 出站代理 —— 这次实际踩到的故障:
   docker compose 会把「运行 compose 的那个 shell」里的 http_proxy/https_proxy
   自动注入容器。登录 shell 里是 127.0.0.1:7890, 而 127.0.0.1 在容器里指向容器自己,
   于是 Gitea 启动时 OIDC discovery 失败:
     initOAuth2Sources() [E] Unable to register source: 高程统一身份认证 due to
     proxyconnect tcp: dial tcp 127.0.0.1:7890: connect: connection refused
   认证源注册不上 -> 登录页按钮照旧显示(数据来自数据库), 但点下去
   /QA/user/oauth2/... 返回 404, 统一身份认证完全无法登录。
   现在两处 compose 都显式给出这四个变量(默认 = 改造前宿主机上的代理设置,
   NO_PROXY 含 10.80.42.185 让 OIDC 直连), 显式赋值可挡住自动注入;
   .env.example 说明如何覆盖/置空, README 记为新陷阱 6(含一行验证命令)。

2) 通行密钥: [service] ENABLE_PASSKEY_AUTHENTICATION=false(两处 compose)。
   登录页此前那个"空方框"就是它: 上游该区块只有 tw-hidden 元素, 浏览器不支持
   条件中介时 CSS 隐藏一切, 只剩一个带边框的 segment。关掉后连区块都不再输出。

实测: 生产 up -d 后 OIDC 入口 307 -> https://cpp.tongji.sh/oidc/auth?client_id=tjhlp-gitea...
(修复前是 404), 登录页 200 且两张卡片正常, healthz 200。
2026-09-13 16:31:40 +08:00

897 lines
40 KiB
Markdown

# 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` |
| 出问题了 | §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` 现在**显式**给出这四个变量(默认 = 改造前宿主机上的代理设置,
> 且 `NO_PROXY` 含 `10.80.42.185` 让 OIDC 走直连), 显式赋值可以挡住自动注入。
> 改代理见 `.env.example` 的同名段落。**每次 `up -d` 后建议验一次**:
> ```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: https://cpp.tongji.sh/oidc/auth?... (404 = 认证源没注册上)
> ```
---
## 3. 本机关键事实
| 项目 | 实测值 |
|---|---|
| 系统 / 架构 | Rocky Linux 8.10 / **aarch64** |
| 对外地址 | `https://cpp.tongji.sh/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 '<title>[^<]*</title>'
# 期望: <title>Sign In - 你的站点名</title>
```
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"*
(<https://docs.docker.com/engine/install/linux-postinstall/>)。
- **`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-<db>.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 https://cpp.tongji.sh/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/<ver>/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), 指向
`https://cpp.tongji.sh/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' \
https://cpp.tongji.sh/oidc/.well-known/openid-configuration
# 2. 容器内能不能拿到(网络路径不同, 这一条才是 Gitea 真正走的)
sudo docker compose exec -T gitea curl -s -o /dev/null -w 'cont -> %{http_code}\n' \
https://cpp.tongji.sh/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 <user>`;
- 本机 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(与迁移前路径一致);
- 站点名正确渲染: `<title>Sign In - 同济高程-答疑平台</title>`;
- 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` 验一次)。