From 79256c5be0b4050a91c37e08d1090ef2d8483a22f966f52a068e61be9397ab44 Mon Sep 17 00:00:00 2001 From: Maoayo233 Date: Fri, 11 Sep 2026 16:00:15 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=96=B0=E5=A2=9E=20Docker=20Compose?= =?UTF-8?q?=20=E9=83=A8=E7=BD=B2=E6=96=B9=E6=A1=88,=20=E7=A7=BB=E9=99=A4?= =?UTF-8?q?=E6=9C=AA=E9=AA=8C=E8=AF=81=E7=9A=84=20ansible=20=E8=8D=89?= =?UTF-8?q?=E6=A1=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 原 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 登录源注册正常。 --- .gitignore | 5 +- README.md | 36 +- ansible/.yamllint.yml | 13 - ansible/README.md | 206 ----- ansible/ansible.cfg | 10 - ansible/inventory/group_vars/all.yml | 42 - ansible/inventory/hosts.yml | 7 - ansible/playbook.yml | 54 -- ansible/requirements.yml | 4 - ansible/roles/common/tasks/main.yml | 61 -- ansible/roles/gitea/handlers/main.yml | 9 - ansible/roles/gitea/tasks/configure.yml | 100 --- ansible/roles/gitea/tasks/install.yml | 50 -- ansible/roles/gitea/tasks/main.yml | 8 - ansible/roles/gitea/templates/app.ini.j2 | 75 -- .../roles/gitea/templates/gitea.service.j2 | 28 - ansible/roles/postgresql/handlers/main.yml | 5 - ansible/roles/postgresql/tasks/main.yml | 73 -- .../roles/postgresql/templates/pg_hba.conf.j2 | 15 - deploy/.env.example | 95 ++ deploy/README.md | 845 ++++++++++++++++++ deploy/compose.yaml | 190 ++++ deploy/db/Dockerfile | 21 + deploy/scripts/backup.sh | 88 ++ deploy/scripts/restore.sh | 209 +++++ deploy/scripts/verify.sh | 120 +++ 26 files changed, 1590 insertions(+), 779 deletions(-) delete mode 100644 ansible/.yamllint.yml delete mode 100644 ansible/README.md delete mode 100644 ansible/ansible.cfg delete mode 100644 ansible/inventory/group_vars/all.yml delete mode 100644 ansible/inventory/hosts.yml delete mode 100644 ansible/playbook.yml delete mode 100644 ansible/requirements.yml delete mode 100644 ansible/roles/common/tasks/main.yml delete mode 100644 ansible/roles/gitea/handlers/main.yml delete mode 100644 ansible/roles/gitea/tasks/configure.yml delete mode 100644 ansible/roles/gitea/tasks/install.yml delete mode 100644 ansible/roles/gitea/tasks/main.yml delete mode 100644 ansible/roles/gitea/templates/app.ini.j2 delete mode 100644 ansible/roles/gitea/templates/gitea.service.j2 delete mode 100644 ansible/roles/postgresql/handlers/main.yml delete mode 100644 ansible/roles/postgresql/tasks/main.yml delete mode 100644 ansible/roles/postgresql/templates/pg_hba.conf.j2 create mode 100644 deploy/.env.example create mode 100644 deploy/README.md create mode 100644 deploy/compose.yaml create mode 100644 deploy/db/Dockerfile create mode 100755 deploy/scripts/backup.sh create mode 100755 deploy/scripts/restore.sh create mode 100755 deploy/scripts/verify.sh diff --git a/.gitignore b/.gitignore index 29e61d4..1ec47fa 100644 --- a/.gitignore +++ b/.gitignore @@ -14,8 +14,9 @@ credentials_*.csv *.pem *.key -# Ansible -*.retry +# Deployment (docker compose) +deploy/.env +deploy/backups/ # IDE .idea/ diff --git a/README.md b/README.md index 23e0cc2..731d700 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ ```text tjhlp-gitea/ -├── ansible/ Ansible 自动化部署(Gitea + PostgreSQL) +├── deploy/ Docker 部署与运维(Gitea + PostgreSQL) ├── issue-templates/ Issue 模板(按仓库类型区分) └── scripts/ Python CLI 管理工具 ``` @@ -26,16 +26,18 @@ tjhlp-gitea/ ### 1. 部署服务器 -需要一台 Rocky Linux 8.10 服务器和本地安装的 Ansible。 +需要一台 Rocky Linux 8.10 服务器, 以及 Docker(含 compose 插件)。 ```bash -cd ansible -# 编辑 inventory/hosts.yml 填入服务器地址 -# 编辑 inventory/group_vars/all.yml 修改域名、密码等 -ansible-playbook playbook.yml +cd deploy +cp .env.example .env # 填写地址、密钥、密码 +docker compose config --quiet # 校验 compose 与 .env 插值 +docker compose up -d --build +sudo ./scripts/verify.sh # 体检 ``` -部署完成后, Ansible 会自动创建管理员账号并输出访问地址。 +完整的部署步骤(Docker 安装、外网代理、RPM 冲突处理), 以及 **备份 / 恢复 / 升级** +流程, 见 [`deploy/README.md`](deploy/README.md)。 ### 2. 初始化平台 @@ -99,13 +101,13 @@ uv run pytest tests/ --cov=tjhlp --cov-report=term-missing # 带覆盖率 - **API 客户端**(client.py)— 使用 [respx](https://lundberg.github.io/respx/) mock HTTP 层, 测试分页、错误处理、404 返回 None - **命令集成**— 使用 Typer CliRunner + mock 测试 setup/users/repos 命令的完整流程 -### Ansible 静态检查 +### 部署配置检查 ```bash -cd ansible -ansible-playbook --syntax-check playbook.yml # 语法检查 -yamllint -c .yamllint.yml . # YAML 格式 -ansible-lint playbook.yml # 最佳实践 +cd deploy +docker compose config --quiet # 校验 compose 与 .env 插值 +sudo ./scripts/verify.sh # 部署后验证(容器健康 + API + 反代) +./scripts/restore.sh --list # 查看可用备份及校验状态 ``` ### Issue Templates 验证 @@ -120,11 +122,11 @@ yamllint issue-templates/ # YAML 语法 | 组件 | 技术选型 | | ------ | ---------- | -| Git 平台 | Gitea(二进制 + systemd) | -| 数据库 | PostgreSQL 18 | -| 服务器 | Rocky Linux 8.10 | -| 部署工具 | Ansible | +| Git 平台 | Gitea(Docker 容器) | +| 数据库 | PostgreSQL 18(Docker 容器) | +| 服务器 | Rocky Linux 8.10 (aarch64) | +| 部署工具 | Docker Compose(见 `deploy/`) | | 管理工具 | Python 3.14 + Typer + httpx + Pydantic + Dynaconf | | 包管理 | uv | | 测试框架 | pytest + respx + pytest-cov | -| 代码检查 | ruff, yamllint, ansible-lint | +| 代码检查 | ruff, yamllint | diff --git a/ansible/.yamllint.yml b/ansible/.yamllint.yml deleted file mode 100644 index a2d4853..0000000 --- a/ansible/.yamllint.yml +++ /dev/null @@ -1,13 +0,0 @@ ---- -extends: default - -rules: - line-length: - max: 160 - truthy: - allowed-values: ["true", "false", "yes", "no"] - comments: - min-spaces-from-content: 1 - indentation: - spaces: 2 - indent-sequences: consistent diff --git a/ansible/README.md b/ansible/README.md deleted file mode 100644 index d4d9305..0000000 --- a/ansible/README.md +++ /dev/null @@ -1,206 +0,0 @@ -# Ansible 部署 - -使用 Ansible 在 Rocky Linux 8.10 服务器上自动部署 Gitea + PostgreSQL 18。 - -## 前置要求 - -- 控制机安装 Ansible >= 2.12 -- 目标服务器运行 Rocky Linux 8.10(或兼容的 RHEL 8 系发行版) -- 控制机可通过 SSH 连接目标服务器(建议配置密钥认证) -- 安装 Ansible 依赖(collection): - ```bash - ansible-galaxy collection install -r requirements.yml - ``` - -## 目录结构 - -``` -ansible/ -├── ansible.cfg Ansible 配置 -├── playbook.yml 主 Playbook -├── requirements.yml Ansible collection 依赖 -├── .yamllint.yml YAML lint 配置 -├── inventory/ -│ ├── hosts.yml 主机清单 -│ └── group_vars/ -│ └── all.yml 全局变量 -└── roles/ - ├── common/ 基础系统配置 - │ └── tasks/main.yml - ├── postgresql/ PostgreSQL 18 安装与配置 - │ ├── tasks/main.yml - │ ├── handlers/main.yml - │ └── templates/ - │ └── pg_hba.conf.j2 - └── gitea/ Gitea 安装与配置 - ├── tasks/ - │ ├── main.yml - │ ├── install.yml 下载二进制(在线获取最新版本) - │ └── configure.yml 生成配置、创建管理员 - ├── handlers/main.yml - └── templates/ - ├── app.ini.j2 Gitea 配置文件模板 - └── gitea.service.j2 systemd 服务文件 -``` - -## 配置 - -### 1. 主机清单 - -编辑 `inventory/hosts.yml`: - -```yaml -all: - hosts: - gitea-server: - ansible_host: 192.168.1.100 # 替换为实际 IP - ansible_user: root -``` - -### 2. 变量配置 - -编辑 `inventory/group_vars/all.yml`, **必须修改**的项: - -| 变量 | 说明 | 默认值 | -|------|------|--------| -| `gitea_domain` | Gitea 访问域名或 IP | `gitea.example.com` | -| `gitea_admin_password` | 管理员初始密码 | `ChangeMe!2025` | -| `gitea_db_password` | 数据库密码 | `change_this_db_password` | - -可选变量: - -| 变量 | 说明 | 默认值 | -|------|------|--------| -| `gitea_version` | 指定 Gitea 版本, 留空自动获取最新 | `""` | -| `gitea_http_port` | HTTP 端口 | `3000` | -| `gitea_admin_user` | 管理员用户名 | `admin` | -| `gitea_admin_email` | 管理员邮箱 | `admin@tongji.edu.cn` | -| `postgresql_version` | PostgreSQL 版本号 | `18` | -| `gitea_secret_key` | 安全密钥, 留空自动生成 | `""` | -| `gitea_internal_token` | 内部令牌, 留空自动生成 | `""` | - -**安全建议**: 生产部署时, `gitea_admin_password` 和 `gitea_db_password` 应使用 `ansible-vault` 加密, 而非明文写在 `all.yml` 中。 - -## 使用方法 - -### 完整部署 - -```bash -ansible-playbook playbook.yml -``` - -### 按 Role 单独运行 - -```bash -# 仅运行基础配置 -ansible-playbook playbook.yml --tags common - -# 仅运行 PostgreSQL -ansible-playbook playbook.yml --tags postgresql - -# 仅运行 Gitea(安装 + 配置) -ansible-playbook playbook.yml --tags gitea -``` - -### 更新系统软件包(默认不执行) - -```bash -ansible-playbook playbook.yml --tags update-system -``` - -## Role 说明 - -### common - -- 安装基础软件包(git, wget, curl 等) -- 创建 `git` 系统用户 -- 配置 firewalld 开放 Gitea 端口 -- 创建 Gitea 所需的目录结构并设置权限 - -### postgresql - -- 添加 PostgreSQL 官方 Yum 仓库 -- 禁用系统自带的 postgresql 模块 -- 安装 PostgreSQL(版本由 `postgresql_version` 变量控制, 默认 18)并初始化数据库集群 -- 配置 `pg_hba.conf` 认证方式为 md5 -- 创建 Gitea 所需的数据库和用户 - -### gitea - -- **安装**: 在线获取最新版本号(通过 `dl.gitea.com/gitea/version.json`), 下载对应的 linux-amd64 二进制到 `/usr/local/bin/gitea`。支持通过 `gitea_version` 变量锁定版本 -- **配置**: 通过 `gitea generate secret` 自动生成安全密钥, 渲染 `app.ini` 配置模板(禁用注册、禁用邮件、启用 Webhook), 部署 systemd 服务 -- **初始化**: 等待 Gitea 启动后, 通过 `gitea admin user create` 创建管理员账号 - -### app.ini 关键配置 - -| 配置项 | 值 | 说明 | -|--------|-----|------| -| `INSTALL_LOCK` | `true` | 跳过 Web 安装向导 | -| `DISABLE_REGISTRATION` | `true` | 禁止自助注册 | -| `ENABLE_NOTIFY_MAIL` | `false` | 不使用邮件通知 | -| `ALLOWED_HOST_LIST` | `*` | 允许 Webhook 访问任意主机 | -| `DEFAULT_REPO_UNITS` | `repo.code,repo.issues` | 新仓库默认只开启代码和 Issue | - -## 部署完成后 - -Playbook 执行完毕后会输出: - -``` -========================================== -Gitea 答疑平台部署完成! -========================================== -访问地址: http://gitea.example.com:3000 -管理员: admin -========================================== -后续步骤: -1. 登录管理员账号并修改初始密码 -2. 创建 API Token (设置 -> 应用 -> 生成令牌) -3. 配置 Python CLI 工具并执行 tjhlp setup init -========================================== -``` - -## 测试与验证 - -### 静态检查 - -无需连接服务器即可执行: - -```bash -# Playbook 语法检查 -ansible-playbook --syntax-check playbook.yml - -# YAML 格式检查(需要 pip install yamllint) -yamllint -c .yamllint.yml . - -# Ansible 最佳实践检查(需要 pip install ansible-lint) -ansible-lint playbook.yml -``` - -### Dry Run - -模拟执行, 不做实际变更(需要能 SSH 到目标服务器): - -```bash -ansible-playbook playbook.yml --check -``` - -### 集成测试(可选) - -如果需要在本地完整测试部署流程, 推荐使用 [Molecule](https://ansible.readthedocs.io/projects/molecule/) + Vagrant: - -```bash -pip install molecule molecule-vagrant pytest-testinfra -cd roles/gitea && molecule test -``` - -由于 Rocky 8 + systemd 在 Docker 中支持不完整, Vagrant(VirtualBox)是更可靠的测试环境。 - -### 部署后验证清单 - -部署完成后应检查: - -- [ ] Gitea Web 界面可访问(`http://{domain}:{port}`) -- [ ] 管理员账号可登录 -- [ ] PostgreSQL 服务运行中(`systemctl status postgresql-{version}`) -- [ ] Gitea 服务运行中(`systemctl status gitea`) -- [ ] 防火墙已开放对应端口(`firewall-cmd --list-ports`) diff --git a/ansible/ansible.cfg b/ansible/ansible.cfg deleted file mode 100644 index 3de4c64..0000000 --- a/ansible/ansible.cfg +++ /dev/null @@ -1,10 +0,0 @@ -[defaults] -inventory = inventory/hosts.yml -roles_path = roles -host_key_checking = False -retry_files_enabled = False - -[privilege_escalation] -become = True -become_method = sudo -become_user = root diff --git a/ansible/inventory/group_vars/all.yml b/ansible/inventory/group_vars/all.yml deleted file mode 100644 index ccfd136..0000000 --- a/ansible/inventory/group_vars/all.yml +++ /dev/null @@ -1,42 +0,0 @@ ---- -# ============================================================================= -# Gitea 答疑平台部署变量 -# ============================================================================= - -# ----------------------------------------------------------------------------- -# Gitea 基础配置 -# ----------------------------------------------------------------------------- -# 留空则自动获取最新版本, 填写则使用指定版本(如 "1.25.1") -gitea_version: "" - -gitea_http_port: 3000 -gitea_domain: "gitea.example.com" # 替换为实际域名或 IP -gitea_app_name: "同济大学高级语言程序设计答疑平台" - -# ----------------------------------------------------------------------------- -# Gitea 管理员账号(首次部署自动创建, 部署后请修改密码) -# ----------------------------------------------------------------------------- -gitea_admin_user: "admin" -gitea_admin_password: "ChangeMe!2026" # 部署后务必修改 -gitea_admin_email: "shenjian@tongji.edu.cn" - -# ----------------------------------------------------------------------------- -# PostgreSQL 数据库配置 -# ----------------------------------------------------------------------------- -postgresql_version: 18 -gitea_db_name: "gitea" -gitea_db_user: "gitea" -gitea_db_password: "change_this_db_password" # 请修改为强密码 - -# ----------------------------------------------------------------------------- -# Webhook 配置 -# ----------------------------------------------------------------------------- -gitea_webhook_allowed_hosts: "*" -gitea_webhook_skip_tls: "false" - -# ----------------------------------------------------------------------------- -# 安全密钥(留空则自动生成, 生成后建议记录保存) -# ----------------------------------------------------------------------------- -gitea_secret_key: "" -gitea_internal_token: "" -gitea_lfs_jwt_secret: "" diff --git a/ansible/inventory/hosts.yml b/ansible/inventory/hosts.yml deleted file mode 100644 index 1569faf..0000000 --- a/ansible/inventory/hosts.yml +++ /dev/null @@ -1,7 +0,0 @@ ---- -all: - hosts: - gitea-server: - ansible_host: 192.168.1.100 # 替换为实际服务器 IP - ansible_user: root # 替换为实际 SSH 用户 - # ansible_ssh_private_key_file: ~/.ssh/id_rsa diff --git a/ansible/playbook.yml b/ansible/playbook.yml deleted file mode 100644 index 200b7db..0000000 --- a/ansible/playbook.yml +++ /dev/null @@ -1,54 +0,0 @@ ---- -# ============================================================================= -# Gitea 答疑平台部署 Playbook -# -# 使用方法: -# ansible-playbook playbook.yml -# -# 仅运行某个 role: -# ansible-playbook playbook.yml --tags postgresql -# ansible-playbook playbook.yml --tags gitea -# ============================================================================= - -- name: 部署 Gitea 答疑平台 - hosts: all - become: true - - pre_tasks: - - name: 检查操作系统 - assert: - that: - - ansible_os_family == "RedHat" - - ansible_distribution_major_version | int >= 8 - fail_msg: "此 Playbook 仅支持 RHEL/Rocky Linux 8+" - - - name: 更新系统软件包 - dnf: - name: "*" - state: latest - tags: [never, update-system] - - roles: - - role: common - tags: [common] - - role: postgresql - tags: [postgresql, database] - - role: gitea - tags: [gitea] - - post_tasks: - - name: 部署完成信息 - debug: - msg: | - ========================================== - Gitea 答疑平台部署完成! - ========================================== - 访问地址: http://{{ gitea_domain }}:{{ gitea_http_port }} - 管理员: {{ gitea_admin_user }} - Gitea 版本: {{ gitea_resolved_version }} - ========================================== - 后续步骤: - 1. 登录管理员账号并修改初始密码 - 2. 创建 API Token (设置 -> 应用 -> 生成令牌) - 3. 配置 Python CLI 工具并执行 tjhlp setup init - ========================================== diff --git a/ansible/requirements.yml b/ansible/requirements.yml deleted file mode 100644 index 55dc059..0000000 --- a/ansible/requirements.yml +++ /dev/null @@ -1,4 +0,0 @@ ---- -collections: - - name: community.postgresql - version: ">=3.0.0" diff --git a/ansible/roles/common/tasks/main.yml b/ansible/roles/common/tasks/main.yml deleted file mode 100644 index e02a914..0000000 --- a/ansible/roles/common/tasks/main.yml +++ /dev/null @@ -1,61 +0,0 @@ ---- -# roles/common/tasks/main.yml -# 基础系统配置: 安装依赖包、创建 git 用户、配置防火墙、创建目录结构 - -- name: 安装基础依赖包 - dnf: - name: - - git - - wget - - curl - state: present - -- name: 创建 git 用户组 - group: - name: git - system: yes - state: present - -- name: 创建 git 系统用户 - user: - name: git - group: git - system: yes - shell: /bin/bash - home: /home/git - create_home: yes - comment: "Git Version Control" - -- name: 创建 Gitea 数据目录 - file: - path: "{{ item.path }}" - state: directory - owner: "{{ item.owner }}" - group: "{{ item.group }}" - mode: "{{ item.mode }}" - loop: - - { path: /var/lib/gitea, owner: git, group: git, mode: "0750" } - - { path: /var/lib/gitea/custom, owner: git, group: git, mode: "0750" } - - { path: /var/lib/gitea/data, owner: git, group: git, mode: "0750" } - - { path: /var/lib/gitea/log, owner: git, group: git, mode: "0750" } - -- name: 创建 Gitea 配置目录 - file: - path: /etc/gitea - state: directory - owner: root - group: git - mode: "0770" - -- name: 确保 firewalld 正在运行 - systemd: - name: firewalld - state: started - enabled: yes - -- name: 开放 Gitea HTTP 端口 - firewalld: - port: "{{ gitea_http_port }}/tcp" - permanent: yes - immediate: yes - state: enabled diff --git a/ansible/roles/gitea/handlers/main.yml b/ansible/roles/gitea/handlers/main.yml deleted file mode 100644 index d56328c..0000000 --- a/ansible/roles/gitea/handlers/main.yml +++ /dev/null @@ -1,9 +0,0 @@ ---- -- name: 重载 systemd - systemd: - daemon_reload: yes - -- name: 重启 Gitea - systemd: - name: gitea - state: restarted diff --git a/ansible/roles/gitea/tasks/configure.yml b/ansible/roles/gitea/tasks/configure.yml deleted file mode 100644 index 5810034..0000000 --- a/ansible/roles/gitea/tasks/configure.yml +++ /dev/null @@ -1,100 +0,0 @@ ---- -# roles/gitea/tasks/configure.yml -# 配置 Gitea: 生成密钥、app.ini、systemd 服务、创建管理员 - -- name: 生成 SECRET_KEY - command: /usr/local/bin/gitea generate secret SECRET_KEY - register: gitea_secret_key_result - changed_when: false - when: gitea_secret_key is not defined or gitea_secret_key == "" - -- name: 保存 SECRET_KEY - set_fact: - gitea_secret_key: "{{ gitea_secret_key_result.stdout }}" - when: gitea_secret_key is not defined or gitea_secret_key == "" - -- name: 生成 INTERNAL_TOKEN - command: /usr/local/bin/gitea generate secret INTERNAL_TOKEN - register: gitea_internal_token_result - changed_when: false - when: gitea_internal_token is not defined or gitea_internal_token == "" - -- name: 保存 INTERNAL_TOKEN - set_fact: - gitea_internal_token: "{{ gitea_internal_token_result.stdout }}" - when: gitea_internal_token is not defined or gitea_internal_token == "" - -- name: 生成 LFS_JWT_SECRET - command: /usr/local/bin/gitea generate secret LFS_JWT_SECRET - register: gitea_lfs_jwt_result - changed_when: false - when: gitea_lfs_jwt_secret is not defined or gitea_lfs_jwt_secret == "" - -- name: 保存 LFS_JWT_SECRET - set_fact: - gitea_lfs_jwt_secret: "{{ gitea_lfs_jwt_result.stdout }}" - when: gitea_lfs_jwt_secret is not defined or gitea_lfs_jwt_secret == "" - -- name: 部署 Gitea 配置文件 - template: - src: app.ini.j2 - dest: /etc/gitea/app.ini - owner: root - group: git - mode: "0640" - notify: 重启 Gitea - -- name: 部署 systemd 服务文件 - template: - src: gitea.service.j2 - dest: /etc/systemd/system/gitea.service - owner: root - group: root - mode: "0644" - notify: - - 重载 systemd - - 重启 Gitea - -- name: 启用并启动 Gitea 服务 - systemd: - name: gitea - state: started - enabled: yes - -- name: 等待 Gitea 就绪 - uri: - url: "http://127.0.0.1:{{ gitea_http_port }}/api/v1/version" - method: GET - status_code: 200 - register: gitea_health - until: gitea_health.status == 200 - retries: 30 - delay: 2 - -- name: 显示 Gitea 版本 - debug: - msg: "Gitea {{ gitea_health.json.version }} 已启动" - -- name: 创建管理员账号 - command: > - /usr/local/bin/gitea admin user create - --username {{ gitea_admin_user }} - --password {{ gitea_admin_password }} - --email {{ gitea_admin_email }} - --admin - --config /etc/gitea/app.ini - become: true - become_user: git - environment: - GITEA_WORK_DIR: /var/lib/gitea - register: admin_create - changed_when: "'has been successfully created' in admin_create.stdout" - failed_when: > - admin_create.rc != 0 and - 'already exists' not in admin_create.stderr - no_log: true - -- name: 收紧配置目录权限 - file: - path: /etc/gitea - mode: "0750" diff --git a/ansible/roles/gitea/tasks/install.yml b/ansible/roles/gitea/tasks/install.yml deleted file mode 100644 index 639b0af..0000000 --- a/ansible/roles/gitea/tasks/install.yml +++ /dev/null @@ -1,50 +0,0 @@ ---- -# roles/gitea/tasks/install.yml -# 下载并安装 Gitea 二进制文件 - -- name: 获取 Gitea 最新版本信息 - uri: - url: https://dl.gitea.com/gitea/version.json - return_content: yes - register: gitea_version_json - until: gitea_version_json.status == 200 - retries: 3 - delay: 2 - when: gitea_version == "" - -- name: 解析最新版本号 - set_fact: - gitea_resolved_version: "{{ (gitea_version_json.content | from_json).latest.version }}" - when: gitea_version == "" - -- name: 使用指定版本号 - set_fact: - gitea_resolved_version: "{{ gitea_version }}" - when: gitea_version != "" - -- name: 显示将要安装的 Gitea 版本 - debug: - msg: "将安装 Gitea {{ gitea_resolved_version }}" - -- name: 检查 Gitea 是否已安装 - stat: - path: /usr/local/bin/gitea - register: gitea_binary - -- name: 获取已安装的 Gitea 版本 - command: /usr/local/bin/gitea --version - register: gitea_installed_version - changed_when: false - failed_when: false - when: gitea_binary.stat.exists - -- name: 下载 Gitea 二进制文件 - get_url: - url: "https://dl.gitea.com/gitea/{{ gitea_resolved_version }}/gitea-{{ gitea_resolved_version }}-linux-amd64" - dest: /usr/local/bin/gitea - mode: "0755" - force: yes - when: > - not gitea_binary.stat.exists or - gitea_resolved_version not in (gitea_installed_version.stdout | default('')) - notify: 重启 Gitea diff --git a/ansible/roles/gitea/tasks/main.yml b/ansible/roles/gitea/tasks/main.yml deleted file mode 100644 index 231ca83..0000000 --- a/ansible/roles/gitea/tasks/main.yml +++ /dev/null @@ -1,8 +0,0 @@ ---- -# roles/gitea/tasks/main.yml - -- name: 安装 Gitea - import_tasks: install.yml - -- name: 配置 Gitea - import_tasks: configure.yml diff --git a/ansible/roles/gitea/templates/app.ini.j2 b/ansible/roles/gitea/templates/app.ini.j2 deleted file mode 100644 index 5adb61b..0000000 --- a/ansible/roles/gitea/templates/app.ini.j2 +++ /dev/null @@ -1,75 +0,0 @@ -; Gitea Configuration -; Managed by Ansible - DO NOT EDIT MANUALLY - -APP_NAME = {{ gitea_app_name | default('同济大学高级语言程序设计答疑平台') }} -RUN_USER = git -RUN_MODE = prod -WORK_PATH = /var/lib/gitea - -[database] -DB_TYPE = postgres -HOST = 127.0.0.1:5432 -NAME = {{ gitea_db_name }} -USER = {{ gitea_db_user }} -PASSWD = {{ gitea_db_password }} -SSL_MODE = disable -LOG_SQL = false - -[server] -PROTOCOL = http -DOMAIN = {{ gitea_domain }} -HTTP_ADDR = {{ gitea_http_addr | default('0.0.0.0') }} -HTTP_PORT = {{ gitea_http_port }} -ROOT_URL = http://{{ gitea_domain }}:{{ gitea_http_port }}/ -APP_DATA_PATH = /var/lib/gitea/data -LFS_START_SERVER = true -LFS_JWT_SECRET = {{ gitea_lfs_jwt_secret }} - -[repository] -ROOT = /var/lib/gitea/data/gitea-repositories -DEFAULT_BRANCH = main -DEFAULT_REPO_UNITS = repo.code,repo.issues -DISABLE_STARS = true - -[security] -INSTALL_LOCK = true -SECRET_KEY = {{ gitea_secret_key }} -INTERNAL_TOKEN = {{ gitea_internal_token }} -MIN_PASSWORD_LENGTH = 8 - -[service] -DISABLE_REGISTRATION = true -REQUIRE_SIGNIN_VIEW = false -ENABLE_NOTIFY_MAIL = false -DEFAULT_KEEP_EMAIL_PRIVATE = true -NO_REPLY_ADDRESS = noreply.{{ gitea_domain }} - -[mailer] -ENABLED = false - -[session] -PROVIDER = file -PROVIDER_CONFIG = /var/lib/gitea/data/sessions - -[log] -ROOT_PATH = /var/lib/gitea/log -MODE = file -LEVEL = info - -[webhook] -ALLOWED_HOST_LIST = {{ gitea_webhook_allowed_hosts | default('*') }} -SKIP_TLS_VERIFY = {{ gitea_webhook_skip_tls | default('false') }} - -[api] -ENABLE_SWAGGER = true -MAX_RESPONSE_ITEMS = 100 - -[indexer] -ISSUE_INDEXER_PATH = /var/lib/gitea/data/indexers/issues.bleve - -[picture] -DISABLE_GRAVATAR = true - -[openid] -ENABLE_OPENID_SIGNIN = false -ENABLE_OPENID_SIGNUP = false diff --git a/ansible/roles/gitea/templates/gitea.service.j2 b/ansible/roles/gitea/templates/gitea.service.j2 deleted file mode 100644 index af5ff18..0000000 --- a/ansible/roles/gitea/templates/gitea.service.j2 +++ /dev/null @@ -1,28 +0,0 @@ -[Unit] -Description=Gitea (Git with a cup of tea) -After=syslog.target -After=network.target -After=postgresql-{{ postgresql_version }}.service - -[Service] -Type=simple -User=git -Group=git -WorkingDirectory=/var/lib/gitea -ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini -Restart=always -RestartSec=5s -Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea - -# Resource limits -LimitMEMLOCK=infinity -LimitNOFILE=65535 - -# Sandboxing -ProtectSystem=full -PrivateDevices=yes -PrivateTmp=yes -NoNewPrivileges=true - -[Install] -WantedBy=multi-user.target diff --git a/ansible/roles/postgresql/handlers/main.yml b/ansible/roles/postgresql/handlers/main.yml deleted file mode 100644 index ff841f4..0000000 --- a/ansible/roles/postgresql/handlers/main.yml +++ /dev/null @@ -1,5 +0,0 @@ ---- -- name: 重启 PostgreSQL - systemd: - name: "postgresql-{{ postgresql_version }}" - state: restarted diff --git a/ansible/roles/postgresql/tasks/main.yml b/ansible/roles/postgresql/tasks/main.yml deleted file mode 100644 index cfba9e4..0000000 --- a/ansible/roles/postgresql/tasks/main.yml +++ /dev/null @@ -1,73 +0,0 @@ ---- -# roles/postgresql/tasks/main.yml -# PostgreSQL 安装与配置 - -- name: 禁用系统自带的 postgresql 模块 - command: dnf module disable postgresql -y - register: pg_module_disable - changed_when: "'Nothing to do' not in pg_module_disable.stdout" - failed_when: false - -- name: 安装 PostgreSQL 官方仓库 RPM - dnf: - name: "https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm" - state: present - disable_gpg_check: yes - -- name: 安装 PostgreSQL {{ postgresql_version }} - dnf: - name: - - postgresql{{ postgresql_version }}-server - - postgresql{{ postgresql_version }} - - python3-psycopg2 - state: present - -- name: 检查 PostgreSQL 数据目录是否已初始化 - stat: - path: "/var/lib/pgsql/{{ postgresql_version }}/data/PG_VERSION" - register: pg_data_dir - -- name: 初始化 PostgreSQL 数据库集群 - command: "/usr/pgsql-{{ postgresql_version }}/bin/postgresql-{{ postgresql_version }}-setup initdb" - when: not pg_data_dir.stat.exists - -- name: 部署 pg_hba.conf - template: - src: pg_hba.conf.j2 - dest: "/var/lib/pgsql/{{ postgresql_version }}/data/pg_hba.conf" - owner: postgres - group: postgres - mode: "0600" - notify: 重启 PostgreSQL - -- name: 启用并启动 PostgreSQL 服务 - systemd: - name: "postgresql-{{ postgresql_version }}" - state: started - enabled: yes - -- name: 等待 PostgreSQL 就绪 - wait_for: - port: 5432 - delay: 2 - timeout: 30 - -- name: 创建 Gitea 数据库用户 - become: true - become_user: postgres - community.postgresql.postgresql_user: - name: "{{ gitea_db_user }}" - password: "{{ gitea_db_password }}" - state: present - no_log: true - -- name: 创建 Gitea 数据库 - become: true - become_user: postgres - community.postgresql.postgresql_db: - name: "{{ gitea_db_name }}" - owner: "{{ gitea_db_user }}" - encoding: UTF-8 - lc_collate: en_US.UTF-8 - lc_ctype: en_US.UTF-8 - state: present diff --git a/ansible/roles/postgresql/templates/pg_hba.conf.j2 b/ansible/roles/postgresql/templates/pg_hba.conf.j2 deleted file mode 100644 index de4e506..0000000 --- a/ansible/roles/postgresql/templates/pg_hba.conf.j2 +++ /dev/null @@ -1,15 +0,0 @@ -# PostgreSQL Client Authentication Configuration File -# =================================================== -# Managed by Ansible - DO NOT EDIT MANUALLY - -# TYPE DATABASE USER ADDRESS METHOD - -# "local" is for Unix domain socket connections only -local all postgres peer -local all all md5 - -# IPv4 local connections: -host all all 127.0.0.1/32 md5 - -# IPv6 local connections: -host all all ::1/128 md5 diff --git a/deploy/.env.example b/deploy/.env.example new file mode 100644 index 0000000..eebe499 --- /dev/null +++ b/deploy/.env.example @@ -0,0 +1,95 @@ +# ============================================================================= +# deploy/.env —— 复制为 .env 后填写。.env 已被 .gitignore 排除, 不要提交。 +# +# cp .env.example .env +# +# 已有部署的密钥【不要重新生成】: 从现有 /etc/gitea/app.ini 对应段抄写 +# (INTERNAL_TOKEN / LFS_JWT_SECRET / oauth2 JWT_SECRET 变更会使已发出的令牌失效)。 +# +# 注意: 值里若含 $ 需要写成 $$(compose 会做变量插值); 含 # 或空格要用引号。 +# ============================================================================= + +# ----------------------------------------------------------------------------- +# 路径 +# ----------------------------------------------------------------------------- +# Gitea 数据根目录(容器内挂到 /data), 结构为 gitea/(配置与日志) 与 git/(仓库) +GITEA_DATA_DIR=/srv/gitea +# PostgreSQL 数据目录(容器内挂到 /var/lib/postgresql) +# postgres:18 的布局: 实际数据在 <此目录>/18/docker, +# 所以这里给父目录即可(不要再按老写法挂 /var/lib/postgresql/data) +POSTGRES_DATA_DIR=/srv/pgdata + +# ----------------------------------------------------------------------------- +# 版本(锁定, 便于回滚) +# ----------------------------------------------------------------------------- +GITEA_VERSION=1.27.3 +POSTGRES_VERSION=18.6 + +# ----------------------------------------------------------------------------- +# 对外地址(必须与现有 Apache 反代一致, 否则链接/克隆地址会错) +# 现有: ROOT_URL = http://10.80.42.185/QA +# Apache: ProxyPass /QA http://localhost:2080 +# ----------------------------------------------------------------------------- +GITEA_DOMAIN=10.80.42.185 +GITEA_ROOT_URL=http://10.80.42.185/QA +GITEA_NO_REPLY_ADDRESS=noreply.10.80.42.185 +# 容器发布的回环端口, 必须等于 Apache ProxyPass 的目标端口 +GITEA_HTTP_PORT=2080 +# 离线模式(沿用现有 app.ini 的 OFFLINE_MODE=true) +GITEA_OFFLINE_MODE=true + +# ----------------------------------------------------------------------------- +# 容器内 git 用户 uid/gid —— 必须与 GITEA_DATA_DIR 的属主一致 +# 现有宿主: /var/lib/gitea 属主 git:git = 982:982 +# ----------------------------------------------------------------------------- +GITEA_UID=982 +GITEA_GID=982 + +# ----------------------------------------------------------------------------- +# 站点名 +# ★ 走【裸变量 APP_NAME】(compose 映射为 APP_NAME, 不是 GITEA__*): +# 镜像 /etc/s6/gitea/setup 用 envsubst 渲染模板, 模板第一行是 +# `APP_NAME = $APP_NAME`。GITEA__DEFAULT__APP_NAME 不生效(原因见 README)。 +# 从现有 app.ini 的【顶层】(无段名)抄写真实值; 全新部署才自行取名。 +# ----------------------------------------------------------------------------- +GITEA_APP_NAME=Gitea + +# ----------------------------------------------------------------------------- +# Webhook 出站白名单(逗号分隔; loopback 是内置网络名) +# loopback 为内置项; 其余按实际通知服务填写。 +# 从现有 app.ini 的【[security] 段】抄写真实值。 +# 段位: 1.27 的规范位置就是 [security]; [webhook] 是 v28.0.0 将移除的 +# deprecated fallback(modules/setting/webhook.go)。 +# ----------------------------------------------------------------------------- +GITEA_ALLOWED_HOST_LIST=loopback,example.com + +# ----------------------------------------------------------------------------- +# 密钥 —— 【必须沿用现有值】 +# INTERNAL_TOKEN / LFS_JWT_SECRET / oauth2 JWT_SECRET 变更会使已发出的令牌失效。 +# 从现有 /etc/gitea/app.ini 抄写; 只有全新部署才用 generate secret 生成。 +# +# GITEA_SECRET_KEY 特别说明: +# 现有 /etc/gitea/app.ini **没有** SECRET_KEY, 实例一直在用 Gitea 内置默认值。 +# 默认留空 = 容器同样使用内置默认值, SSO 与已加密数据行为不变。 +# 如需轮换(安全加固), 填一个新的随机值, 但必须在切换后到管理后台 +# 重新填写 OIDC(OAuth2)登录源的 Client Secret, 并验证登录。详见 README。 +# 生成新值: +# docker run --rm docker.gitea.com/gitea:1.27.3 gitea generate secret SECRET_KEY +# ----------------------------------------------------------------------------- +GITEA_SECRET_KEY= +GITEA_INTERNAL_TOKEN= +GITEA_LFS_JWT_SECRET= +GITEA_OAUTH2_JWT_SECRET= + +# ----------------------------------------------------------------------------- +# PostgreSQL(容器内部) +# 现有集群: db=giteadb, user=gitea, collate=zh_CN.UTF-8 +# ----------------------------------------------------------------------------- +POSTGRES_DB=giteadb +POSTGRES_USER=gitea +POSTGRES_PASSWORD= + +# ----------------------------------------------------------------------------- +# 时区 +# ----------------------------------------------------------------------------- +TZ=Asia/Shanghai diff --git a/deploy/README.md b/deploy/README.md new file mode 100644 index 0000000..2da29a2 --- /dev/null +++ b/deploy/README.md @@ -0,0 +1,845 @@ +# 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` | +| 出问题了 | §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. 站点名 `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 +> ``` + +> **⚠️ 4. 用 `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 +> ``` + +--- + +## 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) 拉取并重建 +docker compose pull gitea +docker compose up -d gitea + +# 5) 看迁移日志 + 验证 +docker compose logs --since 5m gitea | grep -iE 'migrat|error|\[F\]' +sudo ./scripts/verify.sh +``` + +**回滚**: 把 `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` 验一次)。 diff --git a/deploy/compose.yaml b/deploy/compose.yaml new file mode 100644 index 0000000..de9bddd --- /dev/null +++ b/deploy/compose.yaml @@ -0,0 +1,190 @@ +# ============================================================================= +# TJHLP Gitea + PostgreSQL 部署(docker compose v2) +# +# 目标环境: Rocky Linux 8.10 / aarch64 +# +# 设计要点: +# * 版本全部锁定(GITEA_VERSION / POSTGRES_VERSION), 可复现、可回滚 +# * Gitea 只发布到 127.0.0.1, 由宿主机 Apache 继续反代 /QA -> 127.0.0.1:2080 +# (不放 0.0.0.0, 避免绕过反代与 TLS 直连 2080) +# * PostgreSQL 只在内部网络暴露, 不发布到宿主机 +# * 所有 app.ini 配置通过 GITEA__section__KEY 环境变量注入(官方镜像支持), +# 不把宿主绝对路径写进配置文件 +# * 数据用 bind mount, 便于备份/检查/回滚(见 deploy/README.md) +# +# 用法: +# cp .env.example .env # 填写密钥与路径 +# docker compose up -d --build +# docker compose ps +# ============================================================================= + +name: gitea + +services: + db: + # 官方镜像只生成 en_US.UTF-8, 而现有集群是 zh_CN.UTF-8, + # 因此需要一个只加 locale 的派生镜像, 保证迁移后排序语义一致。 + build: + context: ./db + args: + POSTGRES_VERSION: ${POSTGRES_VERSION:-18.6} + image: local/gitea-postgres:${POSTGRES_VERSION:-18.6}-zh_CN + container_name: gitea-db + restart: unless-stopped + environment: + POSTGRES_DB: ${POSTGRES_DB:?POSTGRES_DB is required} + POSTGRES_USER: ${POSTGRES_USER:?POSTGRES_USER is required} + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required} + # 与现有集群保持一致: UTF8 + zh_CN.UTF-8 (见 deploy/README.md 的核对结果) + POSTGRES_INITDB_ARGS: "--encoding=UTF8 --locale=zh_CN.UTF-8" + TZ: ${TZ:-Asia/Shanghai} + volumes: + # ★ postgres:18 起数据目录布局变了(见官方 Dockerfile): + # ENV PGDATA /var/lib/postgresql/18/docker + # VOLUME /var/lib/postgresql ← 不再是 .../data + # 所以必须挂到父目录 /var/lib/postgresql。若仍挂 /var/lib/postgresql/data, + # 入口脚本会通过 mountpoint / /proc/self/mountinfo 检测到"未使用的挂载点" + # 并直接 exit 1(docker_error_old_databases)。 + # 宿主机上实际数据落在 ${POSTGRES_DATA_DIR}/18/docker + - ${POSTGRES_DATA_DIR:?POSTGRES_DATA_DIR is required}:/var/lib/postgresql + healthcheck: + test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U \"$$POSTGRES_USER\" -d \"$$POSTGRES_DB\""] + interval: 10s + timeout: 5s + retries: 12 + start_period: 60s + networks: + - gitea-internal + + gitea: + image: docker.gitea.com/gitea:${GITEA_VERSION:?GITEA_VERSION is required} + container_name: gitea + restart: unless-stopped + depends_on: + db: + condition: service_healthy + environment: + # 与宿主机 git 用户 (uid/gid 982) 对齐, 保证 bind mount 权限正确 + USER_UID: ${GITEA_UID:-982} + USER_GID: ${GITEA_GID:-982} + TZ: ${TZ:-Asia/Shanghai} + + # --- 站点名 --------------------------------------------------------- + # ★ 必须用【裸变量 APP_NAME】, 不能用 GITEA__DEFAULT__APP_NAME: + # 镜像的 /etc/s6/gitea/setup 用 envsubst 渲染 /etc/templates/app.ini, + # 模板第一行就是 `APP_NAME = $APP_NAME` —— 裸变量才是它的来源。 + # 而 GITEA__DEFAULT__APP_NAME 到不了顶层 APP_NAME: + # modules/setting/config_env.go 会把段名小写化(strings.ToLower), + # 而 ini 库(gopkg.in/ini.v1)默认段名常量是 "DEFAULT"(大写, 默认区分大小写), + # 于是只会多出一个没用的 [default] 段。 + # 注意: 模板只在 app.ini 不存在时渲染; 已有 app.ini 时改这个变量 + # 需要删掉 app.ini 让容器重新生成(见 README 5.3)。 + APP_NAME: ${GITEA_APP_NAME:?GITEA_APP_NAME is required} + + # --- 数据库 --------------------------------------------------------- + GITEA__database__DB_TYPE: postgres + GITEA__database__HOST: db:5432 + GITEA__database__NAME: ${POSTGRES_DB:?POSTGRES_DB is required} + GITEA__database__USER: ${POSTGRES_USER:?POSTGRES_USER is required} + GITEA__database__PASSWD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required} + GITEA__database__SSL_MODE: disable + GITEA__database__LOG_SQL: "false" + + # --- 服务地址(保留 /QA 子路径, 与现有 Apache 反代一致) --------------- + GITEA__server__PROTOCOL: http + GITEA__server__DOMAIN: ${GITEA_DOMAIN:?GITEA_DOMAIN is required} + GITEA__server__ROOT_URL: ${GITEA_ROOT_URL:?GITEA_ROOT_URL is required} + GITEA__server__HTTP_ADDR: 0.0.0.0 + GITEA__server__HTTP_PORT: "3000" + GITEA__server__APP_DATA_PATH: /data/gitea + # 现有部署未启用 SSH(git 用户无 .ssh/authorized_keys), 故关闭。 + # 如需启用容器内置 SSH, 见 deploy/README.md "启用 SSH 克隆"。 + GITEA__server__DISABLE_SSH: "true" + GITEA__server__LFS_START_SERVER: "true" + GITEA__server__OFFLINE_MODE: ${GITEA_OFFLINE_MODE:-true} + + # --- 路径(全部在 /data 内, 不依赖宿主路径) --------------------------- + GITEA__repository__ROOT: /data/git/repositories + GITEA__lfs__PATH: /data/git/lfs + GITEA__indexer__ISSUE_INDEXER_PATH: /data/gitea/indexers/issues.bleve + GITEA__session__PROVIDER: file + GITEA__session__PROVIDER_CONFIG: /data/gitea/sessions + # 容器里日志直接进 stdout, 用 docker compose logs / journald 查看 + GITEA__log__MODE: console + GITEA__log__LEVEL: info + + # --- 密钥(必须沿用现有值, 否则加密数据/令牌失效) -------------------- + GITEA__security__INSTALL_LOCK: "true" + # 现有 /etc/gitea/app.ini 未设置 SECRET_KEY, 实例实际使用 Gitea 内置默认值。 + # 留空即保持同一行为(SSO/加密数据不受影响); 旋转换 key 见 deploy/README.md。 + GITEA__security__SECRET_KEY: ${GITEA_SECRET_KEY:-} + GITEA__security__INTERNAL_TOKEN: ${GITEA_INTERNAL_TOKEN:?preserve the existing INTERNAL_TOKEN} + GITEA__security__PASSWORD_HASH_ALGO: pbkdf2 + GITEA__server__LFS_JWT_SECRET: ${GITEA_LFS_JWT_SECRET:?preserve the existing LFS_JWT_SECRET} + GITEA__oauth2__JWT_SECRET: ${GITEA_OAUTH2_JWT_SECRET:?preserve the existing JWT_SECRET} + + # --- 注册与登录(与现有 app.ini 一致: 仅允许外部 OIDC 注册) ---------- + GITEA__service__DISABLE_REGISTRATION: "false" + GITEA__service__ALLOW_ONLY_EXTERNAL_REGISTRATION: "true" + GITEA__service__REGISTER_EMAIL_CONFIRM: "false" + GITEA__service__ENABLE_NOTIFY_MAIL: "false" + GITEA__service__ENABLE_CAPTCHA: "false" + GITEA__service__REQUIRE_SIGNIN_VIEW: "false" + GITEA__service__DEFAULT_KEEP_EMAIL_PRIVATE: "false" + GITEA__service__DEFAULT_ALLOW_CREATE_ORGANIZATION: "true" + GITEA__service__DEFAULT_ENABLE_TIMETRACKING: "true" + GITEA__service__NO_REPLY_ADDRESS: ${GITEA_NO_REPLY_ADDRESS:?GITEA_NO_REPLY_ADDRESS is required} + GITEA__mailer__ENABLED: "false" + + # --- OIDC / OAuth2 -------------------------------------------------- + GITEA__openid__ENABLE_OPENID_SIGNIN: "false" + GITEA__openid__ENABLE_OPENID_SIGNUP: "true" + GITEA__oauth2_client__OPENID_CONNECT_SCOPES: profile + GITEA__oauth2_client__ENABLE_AUTO_REGISTRATION: "true" + GITEA__oauth2_client__USERNAME: userid + GITEA__oauth2_client__ACCOUNT_LINKING: auto + # [oauth2] ENABLED 默认即为 true, 现有 app.ini 未显式设置; + # 这里显式声明, 避免上游改默认值时行为漂移 + GITEA__oauth2__ENABLED: "true" + + # --- 管理员限制 ----------------------------------------------------- + GITEA__admin__DISABLE_REGULAR_ORG_CREATION: "true" + GITEA__admin__EXTERNAL_USER_DISABLE_FEATURES: deletion,manage_credentials,change_username,change_full_name + + # --- 其它(沿用现有 app.ini) ---------------------------------------- + GITEA__cron.update_checker__ENABLED: "true" + GITEA__repository.pull-request__DEFAULT_MERGE_STYLE: merge + GITEA__repository.signing__DEFAULT_TRUST_MODEL: committer + + # --- Webhook 出站白名单 --------------------------------------------- + # ★ 该键在 1.27 的规范位置是 [security], 不是 [webhook]。 + # 证据: modules/setting/webhook.go (v1.27.3) + # deprecatedSetting(rootCfg, "webhook", "ALLOWED_HOST_LIST", + # "security", "ALLOWED_HOST_LIST", "v28.0.0") + # Webhook.AllowedHostList = sec.Key("ALLOWED_HOST_LIST").MustString(Security.AllowedHostList) + # 即 [webhook] 是 v28.0.0 将移除的 fallback。而且读取时 [webhook] 的值 + # 【优先于】[security], 所以千万不要两处都写。 + GITEA__security__ALLOWED_HOST_LIST: ${GITEA_ALLOWED_HOST_LIST:?GITEA_ALLOWED_HOST_LIST is required} + # SKIP_TLS_VERIFY 确实属于 [webhook](webhook.go 里就是读 [webhook] 段) + GITEA__webhook__SKIP_TLS_VERIFY: "true" + + volumes: + - ${GITEA_DATA_DIR:?GITEA_DATA_DIR is required}:/data + - /etc/localtime:/etc/localtime:ro + ports: + # 只绑定回环: Apache 反代 /QA -> 127.0.0.1:2080, 不对外暴露 + - "127.0.0.1:${GITEA_HTTP_PORT:-2080}:3000" + # 上游 Dockerfile 里有 "HEALTH-CHECK-ENDPOINT: don't use HEALTHCHECK" 的提示, + # 这里显式提供一个: 镜像内自带 curl, /api/healthz 是官方健康端点。 + healthcheck: + test: ["CMD", "curl", "-fsS", "http://127.0.0.1:3000/api/healthz"] + interval: 15s + timeout: 5s + retries: 10 + start_period: 90s + networks: + - gitea-internal + +networks: + gitea-internal: + driver: bridge diff --git a/deploy/db/Dockerfile b/deploy/db/Dockerfile new file mode 100644 index 0000000..aa1237e --- /dev/null +++ b/deploy/db/Dockerfile @@ -0,0 +1,21 @@ +# ============================================================================= +# PostgreSQL 派生镜像: 补上 zh_CN.UTF-8 locale +# +# 为什么需要: +# 官方 postgres 镜像在构建时只生成了 en_US.UTF-8 +# (见 docker-library/postgres 的 Dockerfile: `echo 'en_US.UTF-8 UTF-8' >> /etc/locale.gen`)。 +# 而 TJHLP 现有集群的 collation 是 zh_CN.UTF-8: +# giteadb | enc=UTF8 | collate=zh_CN.UTF-8 | ctype=zh_CN.UTF-8 +# 若目标集群用 C.UTF-8 / en_US.UTF-8, 恢复后中文文本的排序与索引语义会变, +# 所以这里生成同名 locale, 用 --locale=zh_CN.UTF-8 初始化。 +# +# 除了 locale, 不改动官方镜像的任何行为。 +# ============================================================================= + +ARG POSTGRES_VERSION=18.6 +FROM docker.io/library/postgres:${POSTGRES_VERSION} + +RUN set -eux; \ + sed -i 's/^# *zh_CN\.UTF-8 UTF-8/zh_CN.UTF-8 UTF-8/' /etc/locale.gen; \ + locale-gen zh_CN.UTF-8; \ + locale -a | grep -i 'zh_CN.utf8' diff --git a/deploy/scripts/backup.sh b/deploy/scripts/backup.sh new file mode 100755 index 0000000..c55695c --- /dev/null +++ b/deploy/scripts/backup.sh @@ -0,0 +1,88 @@ +#!/usr/bin/env bash +# ============================================================================= +# 备份正在运行的 Docker 栈 (PostgreSQL + Gitea 数据) +# +# ./backup.sh # 在线备份(不中断服务) +# ./backup.sh --quiesce # 先停 gitea 容器再备份, 得到一致快照 +# +# 产物: deploy/backups/<时间戳>/ +# postgres-.dump pg_dump 自定义格式 +# gitea-data.tar.gz GITEA_DATA_DIR 全量打包 +# MANIFEST.txt 版本/大小/时间 +# SHA256SUMS 校验和 +# ============================================================================= +set -euo pipefail + +DEPLOY_DIR=$(cd "$(dirname "$0")/.." && pwd) +cd "$DEPLOY_DIR" + +QUIESCE=0 +case "${1:-}" in + --quiesce) QUIESCE=1 ;; + -h|--help) sed -n '2,14p' "$0"; exit 0 ;; + "") ;; + *) echo "未知参数: $1" >&2; exit 2 ;; +esac + +[[ -f .env ]] || { echo "错误: 缺少 .env" >&2; exit 1; } + +# 逐行读取 .env, 不做 shell 展开($$ 还原为 $) +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:?}" + +if ! docker compose ps --status running --format '{{.Service}}' 2>/dev/null | grep -q '^db$'; then + echo "错误: db 容器未运行, 先 docker compose up -d" >&2 + exit 1 +fi + +STAMP=$(date +%Y%m%d-%H%M%S) +OUT="${BACKUP_DIR:-$DEPLOY_DIR/backups}/$STAMP" +mkdir -p "$OUT" + +echo "==> 备份目录: $OUT" + +if [[ ${QUIESCE} -eq 1 ]]; then + echo "==> 暂停 gitea 容器以保证数据一致" + docker compose stop gitea +fi + +echo "==> pg_dump ${POSTGRES_DB}" +docker compose exec -T db pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc \ + > "$OUT/postgres-${POSTGRES_DB}.dump" + +echo "==> 打包 Gitea 数据目录 ${GITEA_DATA_DIR}" +tar -C "$(dirname "$GITEA_DATA_DIR")" -czf "$OUT/gitea-data.tar.gz" "$(basename "$GITEA_DATA_DIR")" + +if [[ ${QUIESCE} -eq 1 ]]; then + echo "==> 恢复 gitea 容器" + docker compose start gitea +fi + +{ + echo "created_at: $(date -Is)" + echo "hostname: $(hostname)" + echo "gitea_image: $(docker compose config --format json 2>/dev/null | grep -o '"image"[^,]*' | head -1 || true)" + echo "postgres_db: ${POSTGRES_DB}" + echo "gitea_data_dir: ${GITEA_DATA_DIR}" + echo "quiesced: ${QUIESCE}" + echo + du -h "$OUT"/* 2>/dev/null || true +} > "$OUT/MANIFEST.txt" + +( cd "$OUT" && sha256sum ./* > SHA256SUMS ) + +echo "==> 完成" +cat "$OUT/MANIFEST.txt" +echo +echo "恢复数据库:" +echo " docker compose exec -T db pg_restore -U ${POSTGRES_USER} -d ${POSTGRES_DB} --clean --if-exists < $OUT/postgres-${POSTGRES_DB}.dump" +echo "恢复数据目录:" +echo " docker compose stop gitea && tar -C $(dirname "$GITEA_DATA_DIR") -xzf $OUT/gitea-data.tar.gz && docker compose start gitea" diff --git a/deploy/scripts/restore.sh b/deploy/scripts/restore.sh new file mode 100755 index 0000000..36a3d08 --- /dev/null +++ b/deploy/scripts/restore.sh @@ -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 保存当前状态, 恢复错了还能退回来; +# * 数据目录不做就地覆盖 —— 先把现有目录改名成 .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 + +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 diff --git a/deploy/scripts/verify.sh b/deploy/scripts/verify.sh new file mode 100755 index 0000000..6112cd4 --- /dev/null +++ b/deploy/scripts/verify.sh @@ -0,0 +1,120 @@ +#!/usr/bin/env bash +# ============================================================================= +# 部署后验证 —— 只读 +# +# ./verify.sh # 容器检查需要 docker 权限 +# sudo ./verify.sh # 没加 docker 组时用这个 +# +# 检查容器健康、Gitea API、以及经 Apache 反代的对外地址。 +# ============================================================================= +set -uo pipefail + +DEPLOY_DIR=$(cd "$(dirname "$0")/.." && pwd) +cd "$DEPLOY_DIR" + +ok() { printf ' [ ok ] %s\n' "$1"; } +bad() { printf ' [FAIL] %s\n' "$1"; } +info() { printf ' [info] %s\n' "$1"; } +warn() { printf ' [warn] %s\n' "$1"; } + +# ----------------------------------------------------------------------------- +# 本脚本检查的是【本机】端点, 必须绕过 HTTP 代理。 +# 若 shell 设了 http_proxy 而 no_proxy 未覆盖 127.0.0.1, 回环请求会被代理接管: +# 本机 mihomo 对 127.0.0.1 直接返回 "502 Bad Gateway", 健康的站点会被误报成故障。 +# (实测: 走代理 -> 502; --noproxy '*' -> 200) +# ----------------------------------------------------------------------------- +unset http_proxy https_proxy ftp_proxy all_proxy HTTP_PROXY HTTPS_PROXY FTP_PROXY ALL_PROXY +export no_proxy='*' NO_PROXY='*' +CURL=(curl -sS --noproxy '*' --max-time 10) + +[[ -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 + +HTTP_PORT=${GITEA_HTTP_PORT:-2080} +ROOT_URL=${GITEA_ROOT_URL:-http://127.0.0.1/} +FAIL=0 + +echo "==============================================" +echo " 部署验证" +echo "==============================================" + +echo +echo "-- 容器状态 --" +DOCKER_OK=0 +if docker info >/dev/null 2>&1; then + DOCKER_OK=1 + docker compose ps +else + warn "无法访问 docker daemon —— 容器状态与健康检查跳过" + info " 用 sudo 运行可完整检查: sudo $0" + info " (或把用户加入 docker 组; 那等于免密 root, 取舍见 deploy/README.md 第 3 节)" +fi + +if [[ ${DOCKER_OK} -eq 1 ]]; then + echo + echo "-- 健康检查 --" + # 刚 --force-recreate / restart 过的容器, 在 start_period(60s)内状态是 "starting", + # 这是正常过渡态而不是故障 —— 最多等 60s, 避免把启动过程误报成 [FAIL]。 + # (与下面回环检查是同一类竞态: verify.sh 常常紧接着一次重建被执行。) + for c in gitea-db gitea; do + st="" + for i in $(seq 1 12); do + st=$(docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{else}}{{.State.Status}}{{end}}' "$c" 2>/dev/null || echo missing) + if [[ "$st" != "starting" && "$st" != "created" ]]; then break; fi + if [[ $i -eq 1 ]]; then echo " (${c} 正在启动, 最多等 60s ...)"; fi + sleep 5 + done + if [[ "$st" == "healthy" || "$st" == "running" ]]; then ok "$c: $st"; else bad "$c: $st"; FAIL=1; fi + done +fi + +echo +echo "-- 本机回环 API (127.0.0.1:${HTTP_PORT}) --" +# 刚 restart 过的容器有一小段窗口: docker-proxy 已接管端口, 但 gitea 还没开始 listen, +# 此时 docker-proxy 会返回 502。给最多 30s 的重试, 避免把启动竞态误报成故障。 +# 注意: 这里不用 curl -f —— 我们要的是状态码本身(502 也是有效信息), +# 加了 -f 会退出非 0, 再配合 "|| echo 000" 就会把 502 和 000 拼成 "502000"。 +code="" +for i in $(seq 1 7); do + code=$("${CURL[@]}" -o /dev/null -w '%{http_code}' \ + "http://127.0.0.1:${HTTP_PORT}/api/healthz" 2>/dev/null) || code=000 + if [[ "$code" == "200" ]]; then break; fi + if [[ $i -eq 1 ]]; then echo " (本机 API 尚未就绪, 最多等 30s ...)"; fi + sleep 5 +done +if [[ "$code" == "200" ]]; then ok "/api/healthz -> 200"; else bad "/api/healthz -> $code"; FAIL=1; fi + +ver=$("${CURL[@]}" "http://127.0.0.1:${HTTP_PORT}/api/v1/version" 2>/dev/null || true) +if [[ -n "$ver" ]]; then ok "/api/v1/version -> $ver"; else bad "/api/v1/version 无响应"; FAIL=1; fi + +echo +echo "-- 经 Apache 反代 (${ROOT_URL}) --" +root=${ROOT_URL%/} +code=$("${CURL[@]}" -o /dev/null -w '%{http_code}' "${root}/api/v1/version" 2>/dev/null) || code=000 +if [[ "$code" == "200" ]]; then ok "${root}/api/v1/version -> 200"; else bad "${root}/api/v1/version -> $code (检查 httpd 反代)"; FAIL=1; fi + +if [[ ${DOCKER_OK} -eq 1 ]]; then + echo + echo "-- 日志尾部(容器) --" + docker compose logs --tail=15 gitea 2>/dev/null | sed 's/^/ /' +fi + +echo +if [[ ${FAIL} -eq 0 ]]; then + if [[ ${DOCKER_OK} -eq 1 ]]; then + echo "==> 全部通过" + else + echo "==> HTTP 检查全部通过 (容器状态未检查: 需要 docker 权限)" + fi +else + echo "==> 存在失败项, 请检查上方 [FAIL]" + exit 1 +fi