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 '