SHA256
forked from course-team/tjhlp-gitea
feat: 新增 Docker Compose 部署方案, 移除未验证的 ansible 草案
原 ansible/ 方案从未在任何环境验证过, 且与本机实际状态严重不符(硬编码
amd64 二进制、会覆盖生产 /etc/gitea/app.ini、会启动 firewalld 切断其它
服务、建的库名与现网不一致); 加上宿主机 Rocky 8 的系统 Python 无法升级,
新版 ansible 也跑不起来。改为 Docker Compose。
新增 deploy/:
- compose.yaml 版本锁定; Gitea 只发布 127.0.0.1:2080(Apache 反代无需
改动), PostgreSQL 不发布端口; 配置全部由
GITEA__section__KEY 环境变量注入; 数据用 bind mount
- db/Dockerfile 官方 postgres 只生成 en_US.UTF-8, 这里补 zh_CN.UTF-8,
与现有集群 collation 保持一致
- scripts/ backup.sh(pg_dump + 数据 tar + SHA256SUMS)、
restore.sh(默认 dry-run, 校验后还原, 拒收宿主布局备份)、
verify.sh(容器健康 + 回环 API + 经 Apache 反代)
文档 deploy/README.md 以 部署/备份/恢复/升级 四条流程为主线, 并记录本机
踩过的四个陷阱: PG18 挂载点、s6 chown 守卫、APP_NAME 只能走裸变量、
HTTP 代理导致的假 502。
一次性迁移脚本(install-docker / configure-docker-proxy / preflight /
migrate-from-binary)已清理, 相应步骤内联进文档。
实测: 源 116 表 → 目标 116 表, /api/healthz 200, 经 Apache /QA 200,
站点名与 OIDC 登录源注册正常。
This commit is contained in:
+3
-2
@@ -14,8 +14,9 @@ credentials_*.csv
|
||||
*.pem
|
||||
*.key
|
||||
|
||||
# Ansible
|
||||
*.retry
|
||||
# Deployment (docker compose)
|
||||
deploy/.env
|
||||
deploy/backups/
|
||||
|
||||
# IDE
|
||||
.idea/
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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
|
||||
@@ -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`)
|
||||
@@ -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
|
||||
@@ -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: "[email protected]"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# 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: ""
|
||||
@@ -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
|
||||
@@ -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
|
||||
==========================================
|
||||
@@ -1,4 +0,0 @@
|
||||
---
|
||||
collections:
|
||||
- name: community.postgresql
|
||||
version: ">=3.0.0"
|
||||
@@ -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
|
||||
@@ -1,9 +0,0 @@
|
||||
---
|
||||
- name: 重载 systemd
|
||||
systemd:
|
||||
daemon_reload: yes
|
||||
|
||||
- name: 重启 Gitea
|
||||
systemd:
|
||||
name: gitea
|
||||
state: restarted
|
||||
@@ -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"
|
||||
@@ -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
|
||||
@@ -1,8 +0,0 @@
|
||||
---
|
||||
# roles/gitea/tasks/main.yml
|
||||
|
||||
- name: 安装 Gitea
|
||||
import_tasks: install.yml
|
||||
|
||||
- name: 配置 Gitea
|
||||
import_tasks: configure.yml
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
- name: 重启 PostgreSQL
|
||||
systemd:
|
||||
name: "postgresql-{{ postgresql_version }}"
|
||||
state: restarted
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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 = https://cpp.tongji.sh/QA
|
||||
# Apache: ProxyPass /QA http://localhost:2080
|
||||
# -----------------------------------------------------------------------------
|
||||
GITEA_DOMAIN=10.80.42.185
|
||||
GITEA_ROOT_URL=https://cpp.tongji.sh/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
|
||||
@@ -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** |
|
||||
| 对外地址 | `https://cpp.tongji.sh/QA`(Apache `ProxyPass /QA http://localhost:2080`) |
|
||||
| 数据目录 | `/srv/gitea`(Gitea)、`/srv/pgdata/18/docker`(PG) |
|
||||
| git 用户 | uid/gid = **982:982**(容器内 `USER_UID`/`USER_GID` 必须对齐) |
|
||||
| 库属性 | `UTF8` / `zh_CN.UTF-8` |
|
||||
| 防火墙 | firewalld 已装但**未运行**; SELinux **Disabled** |
|
||||
| Docker | CE **29.8.0**(rhel/8 源), compose 插件 5.5.1 |
|
||||
|
||||
> ⚠️ **Docker 源必须用 `linux/rhel/8`。** `linux/centos/8` 源在 CentOS 8 EOL 后已冻结在
|
||||
> `docker-ce 26.1.3`(2024-04), 照抄 CentOS 教程会装到三年前的老引擎。
|
||||
|
||||
---
|
||||
|
||||
## 4. 部署(全新主机)
|
||||
|
||||
### 4.1 前置条件
|
||||
|
||||
- Rocky Linux 8(aarch64), 有 `sudo` / root;
|
||||
- 宿主机已有 Apache 反代到 `127.0.0.1:2080`(本方案不改 Apache);
|
||||
- 规划好数据目录(默认 `/srv/gitea`、`/srv/pgdata`), 确保有空间。
|
||||
|
||||
### 4.2 安装 Docker CE
|
||||
|
||||
```bash
|
||||
sudo dnf install -y dnf-plugins-core
|
||||
sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
|
||||
sudo dnf install -y --allowerasing \
|
||||
docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
|
||||
sudo systemctl enable --now docker
|
||||
docker --version && docker compose version
|
||||
```
|
||||
|
||||
**`--allowerasing` 是必需的, 不是可选项。** 首次按常规方式安装会失败:
|
||||
|
||||
```
|
||||
package containerd.io-2.3.5-1.el8.aarch64 conflicts with runc provided by runc-4:1.2.9-6.module+el8.10.0+40310...
|
||||
package containerd.io-2.3.5-1.el8.aarch64 obsoletes runc provided by runc-4:1.2.9-6.module+el8.10.0+40310...
|
||||
package podman-4:4.9.4-37... requires runc >= 1.0.0-57, but none of the providers can be installed
|
||||
```
|
||||
|
||||
根因(已逐个版本核对 Docker 源的 `primary.xml`): Docker 源内**全部 30 个版本**的
|
||||
`containerd.io` 都 `Obsoletes` + `Conflicts: runc`, 而 Rocky 8 的 `runc` 被
|
||||
`containers-common`、`podman`、`buildah` 依赖。**所以这不是版本问题 —— 换老版本 Docker
|
||||
一样冲突。Docker CE 与系统 podman 只能二选一。**
|
||||
|
||||
`--allowerasing` 会由 `containerd.io` 取代 `runc`(它自带 runc 二进制), 连带移除 6 个包:
|
||||
`runc` `podman` `podman-catatonit` `buildah` `containers-common` `cockpit-podman`。
|
||||
|
||||
> 执行前先确认这些包没在承载东西: `podman ps -a` 为空、无镜像、无 Quadlet 单元,
|
||||
> `cockpit.socket` inactive + disabled。装完 docker-ce 后 podman 与 docker
|
||||
> **不能再共存**; 想要回 podman 必须先卸载 docker-ce。不接受移除的, 见附录 A。
|
||||
|
||||
### 4.3 配置外网代理(dockerd **不**继承 shell 变量)
|
||||
|
||||
本机访问 docker.io 必须走代理(7890), 但 **`dockerd` 由 systemd 启动, 不会继承你 shell 里的
|
||||
`http_proxy`/`https_proxy`** —— 所以 `curl` 能通、`docker build` 却报 `dial tcp ...: i/o timeout`。
|
||||
雪上加霜的是本机对 `registry-1.docker.io` 的 **DNS 被污染**(实测解析到
|
||||
`2a03:2800:f10f:83:face:b00c:...`, Facebook 地址段), 直连必然超时; 走 HTTP 代理时由代理
|
||||
负责解析域名, 反而正常:
|
||||
|
||||
| 目标 | 直连 | 经代理 `127.0.0.1:7890` |
|
||||
|---|---|---|
|
||||
| `registry-1.docker.io` | `000`(15s 超时) | `401`(0.9s, 正常响应) |
|
||||
| `docker.gitea.com` | `200` | `200` |
|
||||
|
||||
代理要配到**三个互相独立**的地方, 缺一个就有一类操作不生效:
|
||||
|
||||
| 层 | 文件 | 作用 |
|
||||
|---|---|---|
|
||||
| `dockerd` | `/etc/systemd/system/docker.service.d/http-proxy.conf` | 镜像拉取 |
|
||||
| `containerd` | `/etc/systemd/system/containerd.service.d/http-proxy.conf` | 兜底 |
|
||||
| CLI / BuildKit | `~/.docker/config.json` 的 `proxies` 段 | 自动给 `RUN` 步骤注入代理参数 |
|
||||
|
||||
```bash
|
||||
# 1) dockerd
|
||||
sudo mkdir -p /etc/systemd/system/docker.service.d
|
||||
sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf >/dev/null <<'EOF'
|
||||
[Service]
|
||||
Environment="HTTP_PROXY=http://127.0.0.1:7890"
|
||||
Environment="HTTPS_PROXY=http://127.0.0.1:7890"
|
||||
Environment="NO_PROXY=localhost,127.0.0.1,::1,.local,.internal"
|
||||
EOF
|
||||
|
||||
# 2) containerd
|
||||
sudo mkdir -p /etc/systemd/system/containerd.service.d
|
||||
sudo tee /etc/systemd/system/containerd.service.d/http-proxy.conf >/dev/null <<'EOF'
|
||||
[Service]
|
||||
Environment="HTTP_PROXY=http://127.0.0.1:7890"
|
||||
Environment="HTTPS_PROXY=http://127.0.0.1:7890"
|
||||
Environment="NO_PROXY=localhost,127.0.0.1,::1"
|
||||
EOF
|
||||
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart containerd docker
|
||||
|
||||
# 3) CLI / BuildKit(当前用户; 用 sudo 跑 docker 时也要给 root 配一份)
|
||||
mkdir -p ~/.docker
|
||||
cat > ~/.docker/config.json <<'EOF'
|
||||
{
|
||||
"proxies": {
|
||||
"default": {
|
||||
"httpProxy": "http://127.0.0.1:7890",
|
||||
"httpsProxy": "http://127.0.0.1:7890",
|
||||
"noProxy": "localhost,127.0.0.1,::1"
|
||||
}
|
||||
}
|
||||
}
|
||||
EOF
|
||||
sudo cp ~/.docker/config.json /root/.docker/config.json 2>/dev/null || true
|
||||
|
||||
# 端到端验证
|
||||
docker pull hello-world
|
||||
```
|
||||
|
||||
> **已知坑: BuildKit 解析 `FROM` 时不走这个代理。**
|
||||
> `docker pull postgres:18.6` 走 dockerd 自己的 registry 客户端, 会遵守上面的 drop-in;
|
||||
> 但 `docker compose build` 里 `[internal] load metadata` 那一步是 **BuildKit** 在解析
|
||||
> `FROM docker.io/library/postgres:18.6`, 它会**绕过代理直连**, 对 `auth.docker.io`
|
||||
> 做本地 DNS 查询(报 `lookup auth.docker.io on 202.120.190.208:53: i/o timeout`)。
|
||||
> 本机没有独立 `buildkitd`、没有自定义 builder、没有 `daemon.json`, BuildKit 内嵌在
|
||||
> dockerd 里 —— 也就是说代理变量在场却未被采用, 属 BuildKit 解析器的行为, 不是配置写错。
|
||||
>
|
||||
> **规避办法: 先用 `docker pull` 把基础镜像拉到本地**(见 4.5), 之后 BuildKit 直接命中
|
||||
> 本地镜像, 不再访问 registry。
|
||||
|
||||
> 还有**第四件事**: 容器内部的代理(例如让 Gitea 去拉外部头像 / 发外部 webhook)。
|
||||
> 那是 compose `environment:` 的事。当前 `GITEA_OFFLINE_MODE=true`, 暂不需要。
|
||||
|
||||
### 4.4 配置 `.env`
|
||||
|
||||
```bash
|
||||
cd /home/ymy/tjhlp-gitea/deploy
|
||||
cp .env.example .env
|
||||
$EDITOR .env
|
||||
```
|
||||
|
||||
必须有值的键(其余有默认值):
|
||||
|
||||
| 键 | 说明 |
|
||||
|---|---|
|
||||
| `GITEA_ROOT_URL` / `GITEA_DOMAIN` | 必须与 Apache 反代一致, 否则克隆地址与链接会错 |
|
||||
| `GITEA_HTTP_PORT` | 必须等于 Apache `ProxyPass` 的目标端口(本机 `2080`) |
|
||||
| `GITEA_APP_NAME` | 站点名, 走**裸变量**(陷阱 3) |
|
||||
| `GITEA_DATA_DIR` / `POSTGRES_DATA_DIR` | 数据落盘位置 |
|
||||
| `GITEA_UID` / `GITEA_GID` | 必须等于数据目录属主(本机 `982:982`) |
|
||||
| `POSTGRES_DB` / `POSTGRES_USER` / `POSTGRES_PASSWORD` | 数据库 |
|
||||
| `GITEA_INTERNAL_TOKEN` / `GITEA_LFS_JWT_SECRET` / `GITEA_OAUTH2_JWT_SECRET` | 密钥, 生成见下 |
|
||||
| `GITEA_SECRET_KEY` | 见 §11; 留空 = 用 Gitea 内置默认值 |
|
||||
|
||||
```bash
|
||||
# 生成密钥
|
||||
docker run --rm docker.gitea.com/gitea:1.27.3 gitea generate secret INTERNAL_TOKEN
|
||||
docker run --rm docker.gitea.com/gitea:1.27.3 gitea generate secret LFS_JWT_SECRET
|
||||
docker run --rm docker.gitea.com/gitea:1.27.3 gitea generate secret JWT_SECRET # -> OAUTH2_JWT_SECRET
|
||||
docker run --rm docker.gitea.com/gitea:1.27.3 gitea generate secret SECRET_KEY
|
||||
```
|
||||
|
||||
**校验配置**(取代了早先的 `preflight.sh`; 只读, 不需要 daemon):
|
||||
|
||||
```bash
|
||||
docker compose config --quiet && echo "compose 插值 OK"
|
||||
docker compose config | grep -E 'APP_NAME|ALLOWED_HOST|image:' # 抽查关键项
|
||||
```
|
||||
|
||||
### 4.5 启动
|
||||
|
||||
```bash
|
||||
cd /home/ymy/tjhlp-gitea/deploy
|
||||
|
||||
# ★ 先预拉基础镜像, 绕开 BuildKit 的 FROM 解析(见 4.3)
|
||||
docker pull docker.io/library/postgres:18.6
|
||||
docker pull docker.gitea.com/gitea:1.27.3
|
||||
|
||||
docker compose up -d --build
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
首次启动 `db` 会 `initdb`(`UTF8` + `zh_CN.UTF-8`), `gitea` 会自动建表。
|
||||
|
||||
### 4.6 验证
|
||||
|
||||
```bash
|
||||
sudo ./scripts/verify.sh
|
||||
```
|
||||
|
||||
检查: 两个容器 `healthy`、`/api/healthz` 200、`/api/v1/version` 版本正确、经 Apache `/QA` 200。
|
||||
站点名与登录源可以单独确认:
|
||||
|
||||
```bash
|
||||
curl -sS --noproxy '*' http://127.0.0.1:2080/user/login | grep -o '<title>[^<]*</title>'
|
||||
# 期望: <title>Sign In - 你的站点名</title>
|
||||
```
|
||||
|
||||
locale 是否真的生效:
|
||||
|
||||
```bash
|
||||
docker compose exec -T db psql -U gitea -d giteadb -tAc \
|
||||
"select datname, pg_encoding_to_char(encoding), datcollate from pg_database where datname='giteadb'"
|
||||
# 期望: giteadb | UTF8 | zh_CN.UTF-8
|
||||
```
|
||||
|
||||
### 4.7 收尾
|
||||
|
||||
**若是从宿主二进制部署迁移过来的, 必须停用宿主 unit。** 否则重启后宿主 gitea 与容器会抢
|
||||
`127.0.0.1:2080` —— 两边都会开机自启(`docker.service` enabled, 容器
|
||||
`restart: unless-stopped`), 谁先 bind 谁赢。若宿主赢了, 平台会**静默地**退回旧库运行:
|
||||
容器起不来, 但 Apache `/QA` 依然返回 200, 从外部**完全看不出来**。
|
||||
|
||||
```bash
|
||||
sudo systemctl disable gitea # 容器侧开机会自己回来, 不需要宿主 unit
|
||||
```
|
||||
|
||||
**要不要把用户加进 `docker` 组?** 加了确实方便 —— `docker` 命令不用 `sudo`,
|
||||
`verify.sh` / `backup.sh` / `restore.sh` 都能直接跑。但这是一次实打实的权限降级:
|
||||
|
||||
- **`docker` 组等价于免密 root。** 组内用户可以
|
||||
`docker run -v /:/host -it alpine chroot /host` 直接拿到宿主 root shell。
|
||||
Docker 官方文档同样说明 *"The docker group grants root-level privileges to the user"*
|
||||
(<https://docs.docker.com/engine/install/linux-postinstall/>)。
|
||||
- **`wheel` 与 `docker` 组的区别就在密码。** 已加入 `wheel` 的话 `sudo` **需要输密码**;
|
||||
`docker` 组**不需要**。一旦有人拿到一个 `ymy` 的 shell(SSH 会话劫持、被投毒的脚本或依赖、
|
||||
code-server 会话), `wheel` 还挡着一道密码, `docker` 组则直接就是 root。
|
||||
- **这台机器是共享的。** Apache/PHP 对整个平台提供 Web 服务, 还跑着 MySQL、Redis、
|
||||
code-server。root 沦陷的爆炸半径是整台机器, 不只是 Gitea。
|
||||
|
||||
**建议: 不加, 继续用 `sudo`。** 日常 docker 命令用得很少 —— `restart: unless-stopped`
|
||||
让容器开机自动拉起, 平时只有偶尔看日志/升级/备份, `sudo` 的开销基本可忽略。
|
||||
|
||||
若确实想要免密, 比进 `docker` 组**更安全**的做法是给一个只放行固定动作的 wrapper +
|
||||
sudoers 规则(**不能**直接放行裸 `docker`, 那等于没限制):
|
||||
|
||||
```bash
|
||||
# /usr/local/sbin/gitea-ctl —— 只暴露固定动作
|
||||
#!/usr/bin/env bash
|
||||
cd /home/ymy/tjhlp-gitea/deploy || exit 1
|
||||
case "${1:-}" in
|
||||
up) exec docker compose up -d ;;
|
||||
down) exec docker compose down ;;
|
||||
ps) exec docker compose ps ;;
|
||||
logs) shift; exec docker compose logs --tail=200 "$@" ;;
|
||||
verify) exec ./scripts/verify.sh ;;
|
||||
backup) exec ./scripts/backup.sh --quiesce ;;
|
||||
*) echo "用法: gitea-ctl {up|down|ps|logs|verify|backup}" >&2; exit 1 ;;
|
||||
esac
|
||||
```
|
||||
|
||||
```
|
||||
# /etc/sudoers.d/gitea-ctl (先用 visudo -f 校验再生效)
|
||||
ymy ALL=(root) NOPASSWD: /usr/local/sbin/gitea-ctl
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 备份
|
||||
|
||||
```bash
|
||||
cd /home/ymy/tjhlp-gitea/deploy
|
||||
sudo ./scripts/backup.sh # 在线备份(不中断服务)
|
||||
sudo ./scripts/backup.sh --quiesce # 先停 gitea 再备份, 一致快照(推荐)
|
||||
```
|
||||
|
||||
**必须用 root 跑**: 打包 `GITEA_DATA_DIR` 时要读取 `.ssh` 等 `700` 目录, 并且要保留文件属主。
|
||||
|
||||
产物在 `deploy/backups/<时间戳>/`:
|
||||
|
||||
| 文件 | 内容 |
|
||||
|---|---|
|
||||
| `postgres-<db>.dump` | `pg_dump -Fc` 自定义格式, 用 `pg_restore` 恢复 |
|
||||
| `gitea-data.tar.gz` | `GITEA_DATA_DIR` 全量打包(**容器布局**) |
|
||||
| `MANIFEST.txt` | 时间/主机/镜像/大小 |
|
||||
| `SHA256SUMS` | 校验和, `restore.sh` 恢复前会验证 |
|
||||
|
||||
`--quiesce` 与在线备份的区别: 在线备份时 Gitea 仍在写库/写仓库, 两份产物之间存在时间差,
|
||||
极端情况下恢复出来的"库"与"仓库"不一致。**做重要节点(升级前、迁移前)一律用 `--quiesce`。**
|
||||
|
||||
**定期备份**(root 的 crontab, 每天 03:00 一致快照):
|
||||
|
||||
```bash
|
||||
sudo crontab -e
|
||||
# 0 3 * * * cd /home/ymy/tjhlp-gitea/deploy && ./scripts/backup.sh --quiesce >> /var/log/gitea-backup.log 2>&1
|
||||
```
|
||||
|
||||
**保留策略**: 备份目录不会被自动清理, 需要自己 prune(数据只有几 MB, 但 `pg_dump` 有 40 MB
|
||||
上下)。建议保留最近 7 份 + 每月 1 份, 并**异地留一份** —— 同一块盘上的备份挡不住盘坏。
|
||||
可以改 `BACKUP_DIR` 指向外部挂载点。
|
||||
|
||||
> ⚠️ `backup.sh` 产出的是**容器布局**的数据包。历史遗留的
|
||||
> `deploy/backups/pre-migration-*/gitea-source-data.tar.gz` 是二进制部署时期的**宿主布局**
|
||||
> (`gitea/data/gitea-repositories/...`), **不能**用 `restore.sh` 恢复数据目录(脚本会拒收)。
|
||||
> 那些备份只有 `postgres-giteadb.dump` 还能用(`--db-only`)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 恢复
|
||||
|
||||
```bash
|
||||
cd /home/ymy/tjhlp-gitea/deploy
|
||||
|
||||
# 1) 看有哪些备份, 以及校验状态(不需要 root)
|
||||
./scripts/restore.sh --list
|
||||
|
||||
# 2) dry-run: 校验校验和 + 打印恢复计划, 不动任何东西
|
||||
./scripts/restore.sh 20260912-030000
|
||||
|
||||
# 3) 真正执行
|
||||
sudo ./scripts/restore.sh 20260912-030000 --apply
|
||||
```
|
||||
|
||||
选项:
|
||||
|
||||
| 选项 | 作用 |
|
||||
|---|---|
|
||||
| `--db-only` | 只恢复数据库(数据目录不动) |
|
||||
| `--data-only` | 只恢复数据目录(库不动) |
|
||||
| `--no-safety-backup` | 跳过"恢复前先备份当前状态"(不建议) |
|
||||
|
||||
`--apply` 的执行顺序:
|
||||
|
||||
1. **校验 `SHA256SUMS`** —— 任一文件不匹配立即中止;
|
||||
2. 跑一次 `backup.sh --quiesce`, 把**当前**状态存下来(恢复错了还能退回去);
|
||||
3. `docker compose up -d db` 并等 `healthy`;
|
||||
4. `docker compose stop gitea`;
|
||||
5. 数据目录: **先把现有目录改名**成 `${GITEA_DATA_DIR}.pre-restore-<时间戳>`(不删除),
|
||||
再解包备份, 然后 `chown -R 982:982`;
|
||||
6. 数据库: `pg_restore --clean --if-exists --no-owner`, 并打印恢复后的表数量;
|
||||
7. `docker compose up -d gitea`, 等 `healthy`, 跑 `verify.sh`;
|
||||
8. 打印数据目录的回退命令。
|
||||
|
||||
脚本失败或恢复错了, 按它打印的命令回退:
|
||||
|
||||
```bash
|
||||
sudo docker compose stop gitea
|
||||
sudo rm -rf /srv/gitea && sudo mv /srv/gitea.pre-restore-<时间戳> /srv/gitea
|
||||
sudo docker compose start gitea
|
||||
```
|
||||
|
||||
**手工等价的恢复命令**(脚本不可用时):
|
||||
|
||||
```bash
|
||||
sudo docker compose stop gitea
|
||||
docker compose exec -T db pg_restore -U gitea -d giteadb --clean --if-exists --no-owner \
|
||||
< backups/<时间戳>/postgres-giteadb.dump
|
||||
sudo mv /srv/gitea /srv/gitea.bak && sudo tar -C /srv -xzf backups/<时间戳>/gitea-data.tar.gz
|
||||
sudo chown -R 982:982 /srv/gitea
|
||||
sudo docker compose up -d
|
||||
```
|
||||
|
||||
> **演练建议**: 至少每学期做一次 —— 在测试机上把最新备份 `--apply` 一遍, 确认站点能起来、
|
||||
> 仓库能 clone、Issue 都在。备份坏了通常是恢复的那一刻才发现。
|
||||
|
||||
恢复后若 Gitea 报 `[F] ... permission denied`, 见陷阱 2 的体检命令。
|
||||
|
||||
---
|
||||
|
||||
## 7. 升级
|
||||
|
||||
> **第一步永远是备份。** Gitea 的数据库迁移不可逆 —— 升级后想退回旧镜像, 旧版本很可能
|
||||
> 因为 schema 版本比它新而拒绝启动, 唯一退路就是备份。
|
||||
|
||||
### 7.1 升级 Gitea
|
||||
|
||||
```bash
|
||||
cd /home/ymy/tjhlp-gitea/deploy
|
||||
|
||||
# 1) 备份(必做)
|
||||
sudo ./scripts/backup.sh --quiesce
|
||||
|
||||
# 2) 读 release notes, 确认没有 breaking change
|
||||
# https://github.com/go-gitea/gitea/releases
|
||||
|
||||
# 3) 改版本
|
||||
sed -i 's/^GITEA_VERSION=.*/GITEA_VERSION=1.28.0/' .env # 或 $EDITOR .env
|
||||
|
||||
# 4) 拉取并重建
|
||||
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/<ver>/docker`), 所以
|
||||
> `POSTGRES_DATA_DIR` 本身不用改, 但**旧目录一定要先改名保留**, 确认新集群没问题再删。
|
||||
> 另外 `pg_restore` 用的 `pg_restore` 二进制应来自**新版本**容器(本方案是在容器内执行,
|
||||
> 天然满足)。
|
||||
|
||||
### 7.3 升级检查单
|
||||
|
||||
- [ ] 已 `backup.sh --quiesce`, 且 `restore.sh --list` 显示校验 `ok`
|
||||
- [ ] 读过 release notes, 确认没有 breaking change(配置文件段位变更、弃用项)
|
||||
- [ ] 避开发答疑高峰, 预留 30 分钟
|
||||
- [ ] 升级后 `verify.sh` 全绿
|
||||
- [ ] 升级后日志无 `[F]` / `[E]`
|
||||
- [ ] 登录一次, 确认 OIDC 登录源与仓库 clone 正常
|
||||
- [ ] 确认无误后再清理旧备份 / 旧数据目录
|
||||
|
||||
---
|
||||
|
||||
## 8. 日常运维
|
||||
|
||||
```bash
|
||||
cd /home/ymy/tjhlp-gitea/deploy
|
||||
|
||||
docker compose ps # 状态(含 health)
|
||||
docker compose logs -f --tail=100 gitea
|
||||
docker compose restart gitea
|
||||
sudo ./scripts/verify.sh # 完整体检
|
||||
docker compose exec -T db psql -U gitea -d giteadb # 进库
|
||||
```
|
||||
|
||||
改了 `compose.yaml` 或 `.env` 之后:
|
||||
|
||||
```bash
|
||||
docker compose up -d # 增量生效(必要时 --force-recreate)
|
||||
```
|
||||
|
||||
改了**只由模板渲染**的键(如 `GITEA_APP_NAME`)则要重建 `app.ini`, 见陷阱 3。
|
||||
|
||||
---
|
||||
|
||||
## 9. 回滚
|
||||
|
||||
**回滚到宿主二进制部署**(源数据与源库都还在原地, 迁移只复制不移动):
|
||||
|
||||
```bash
|
||||
cd /home/ymy/tjhlp-gitea/deploy
|
||||
docker compose down
|
||||
sudo systemctl enable --now gitea # 之前 disable 过, 这里要 enable 回来
|
||||
```
|
||||
|
||||
源数据 `/var/lib/gitea` 与源库 `giteadb` 未被修改, 立即恢复原状。
|
||||
|
||||
**回滚一次升级**: 见 §7 各小节。
|
||||
|
||||
---
|
||||
|
||||
## 10. 外部依赖: OAuth2/OIDC 登录源(`高程统一身份认证`)
|
||||
|
||||
库里有一条 `login_source` 记录(id=1), 指向
|
||||
`https://cpp.tongji.sh/oidc/.well-known/openid-configuration`。**这个服务的可用性不影响
|
||||
Gitea 本身**, 只影响该登录源能否注册。两类日志要分清:
|
||||
|
||||
| 日志 | 级别 | 含义 |
|
||||
|---|---|---|
|
||||
| `Failed to create OpenID Connect Provider ... Non-success code for Discovery URL: 503` | `[W]`/`[E]` | **不致命**。Gitea 跳过该源, 其余功能正常; 页面不显示该登录按钮 |
|
||||
| `asymkey.RewriteAllPublicKeys ... permission denied` | `[F]` | **致命**。进程退出, 容器重启循环(见陷阱 2) |
|
||||
|
||||
Gitea 只在**启动时**注册 OAuth2 源(`initOAuth2Sources()`), 所以:
|
||||
|
||||
> **IdP 恢复后, 必须重启 gitea 容器, 登录源才会被重新注册。**
|
||||
> `sudo docker compose restart gitea`
|
||||
|
||||
IdP 侧改动后的验证步骤(从外到内, 任一步失败都会表现为同一个 503):
|
||||
|
||||
```bash
|
||||
cd /home/ymy/tjhlp-gitea/deploy
|
||||
|
||||
# 1. 宿主机上能不能拿到 discovery 文档(走 Apache -> /oidc)
|
||||
curl -sS --noproxy '*' -o /dev/null -w 'host -> %{http_code}\n' \
|
||||
https://cpp.tongji.sh/oidc/.well-known/openid-configuration
|
||||
|
||||
# 2. 容器内能不能拿到(网络路径不同, 这一条才是 Gitea 真正走的)
|
||||
sudo docker compose exec -T gitea curl -s -o /dev/null -w 'cont -> %{http_code}\n' \
|
||||
https://cpp.tongji.sh/oidc/.well-known/openid-configuration
|
||||
|
||||
# 3. 重启后确认不再有注册失败
|
||||
sudo docker compose restart gitea
|
||||
sudo docker compose logs --since 2m gitea | grep -i 'register source' || echo "OK: 无注册失败"
|
||||
|
||||
# 4. 登录页上该登录源是否出现(应为 1 或更大)
|
||||
curl -sS --noproxy '*' http://127.0.0.1:2080/user/login | grep -c '高程统一身份认证'
|
||||
|
||||
# 5. 库里的记录本身还在(与 IdP 无关, 只是确认没丢这条配置)
|
||||
sudo docker compose exec -T db psql -U gitea -d giteadb -tAc \
|
||||
"select id,name,is_active from login_source"
|
||||
```
|
||||
|
||||
第 1 步通、第 2 步不通, 通常是容器到宿主机 IP 的可达性问题(而不是 IdP 的问题);
|
||||
两步都 503 才是 IdP 侧还没起来。第 4 步为 `0` 说明源仍未注册成功。
|
||||
|
||||
---
|
||||
|
||||
## 11. `SECRET_KEY` 与安全
|
||||
|
||||
Gitea 源码 `modules/setting/security.go`:
|
||||
|
||||
```go
|
||||
SecretKey = loadSecret(sec, "SECRET_KEY_URI", "SECRET_KEY")
|
||||
if SecretKey == "" {
|
||||
// FIXME: ... Until it supports rotating an existing secret key,
|
||||
// we shouldn't move users off of the widely used default value
|
||||
SecretKey = "!#@FDEWREWR&*("
|
||||
}
|
||||
```
|
||||
|
||||
也就是说: 本实例一直在用这个**公开的内置常量**。官方文档对 `SECRET_KEY` 的说明是
|
||||
"if you lost it, the data encrypted by it (like 2FA secret) can't be decrypted anymore"。
|
||||
|
||||
本实例的受影响面很小(已核对): `two_factor = 0`, `webauthn_credential = 0`,
|
||||
唯一的加密相关对象是 1 个 OAuth2 登录源「高程统一身份认证」。
|
||||
|
||||
- **默认**: `.env` 里 `GITEA_SECRET_KEY` 留空 → 沿用同一默认值, **行为完全不变**, SSO 不受影响。
|
||||
- **加固(可选, 需单独安排窗口)**: 生成随机 `SECRET_KEY` 写入 `.env` →
|
||||
`docker compose up -d gitea` → 到管理后台**重新填写 OIDC 登录源的 Client Secret**
|
||||
(这会让它用新密钥重新加密) → 验证 SSO 登录。**跳过重配会导致 OIDC 登录失败。**
|
||||
|
||||
其它安全要点:
|
||||
|
||||
- PostgreSQL 不能发布端口到宿主机; Gitea 只发布回环(见 §1)。
|
||||
- `.env` 含密钥, 已被 `.gitignore` 排除, **不要提交**。
|
||||
- `.env` 值里含 `$` 要写成 `$$`(compose 会做变量插值); 含 `#` 或空格要用引号。
|
||||
|
||||
---
|
||||
|
||||
## 12. 故障排查速查
|
||||
|
||||
| 症状 | 先看 | 处置 |
|
||||
|---|---|---|
|
||||
| 容器 `Restarting` 死循环, `/api/healthz` 不通 | `docker compose logs gitea \| grep '\[F\]'` | `permission denied` → 陷阱 2 |
|
||||
| 页面标题是 `Gitea: Git with a cup of tea` | §2 陷阱 3 | 删 `app.ini` 重建 |
|
||||
| `db` 容器起不来, 日志提 `unused mount/volume` | §2 陷阱 1 | 挂载点应为 `/var/lib/postgresql` |
|
||||
| `curl 127.0.0.1:2080` 返回 502 | §2 陷阱 4 | 加 `--noproxy '*'` |
|
||||
| 登录页没有 `高程统一身份认证` | §10 | 确认 IdP 可达后 `restart gitea` |
|
||||
| 重启后平台"正常但数据是旧的" | — | 宿主 `gitea.service` 抢了 2080, 见 §4.7 |
|
||||
| `docker build` 报 `lookup auth.docker.io ... i/o timeout` | §4.3 | 先 `docker pull` 基础镜像 |
|
||||
| `docker pull` 报 `i/o timeout` | §4.3 | 代理 drop-in 没生效, `systemctl show docker -p Environment` |
|
||||
| 容器 healthy 但站点 503 | `docker compose logs gitea` | 多为 `.env` 里 DB 密码与既有数据不一致 |
|
||||
|
||||
---
|
||||
|
||||
## 13. 附录 A: RPM 冲突的三条路线
|
||||
|
||||
因为 `containerd.io` 与发行版 `runc` 互斥(§4.2), 本机只有三种选择:
|
||||
|
||||
| 路线 | 系统改动 | 代价 |
|
||||
|---|---|---|
|
||||
| **A. Docker + `--allowerasing`**(已采用) | 移除 `runc/podman/podman-catatonit/buildah/containers-common/cockpit-podman` | 与 podman 二选一; 得到 dnf 托管的 Docker CE 29.8.0 |
|
||||
| **B. 保留 podman, 用 Docker 静态二进制** | 不动任何 RPM, 只往 `/usr/local/bin` 放文件 | 不受 dnf 管理: 升级手工做, systemd unit 自己维护 |
|
||||
| **C. 放弃 Docker, 纯 Podman** | 零改动 | 需额外 compose provider; `depends_on: service_healthy` 语义弱, 可能要改写 Quadlet |
|
||||
|
||||
### B. Docker 静态二进制(保留 podman)
|
||||
|
||||
```bash
|
||||
curl -fsSLo /tmp/docker.tgz https://download.docker.com/linux/static/stable/aarch64/docker-29.8.0.tgz
|
||||
tar -C /usr/local --strip-components=1 -xzf /tmp/docker.tgz # dockerd/containerd/runc/docker...
|
||||
mkdir -p /usr/local/lib/docker/cli-plugins
|
||||
curl -fsSLo /usr/local/lib/docker/cli-plugins/docker-compose \
|
||||
https://github.com/docker/compose/releases/latest/download/docker-compose-linux-aarch64
|
||||
chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
|
||||
```
|
||||
|
||||
静态包自带 `runc`/`containerd`, 不碰 RPM 数据库, 因此与 podman 无冲突;
|
||||
但需要自备 systemd unit(`Type=notify`, `ExecStart=/usr/local/bin/dockerd`)。
|
||||
|
||||
### C. 纯 Podman
|
||||
|
||||
```bash
|
||||
sudo dnf install -y podman-compose # 或用 Go 版 docker-compose 二进制作 provider
|
||||
podman compose up -d
|
||||
```
|
||||
|
||||
注意:
|
||||
|
||||
- rootless 容器要开机自启/登出后存活, 需要 `sudo loginctl enable-linger <user>`;
|
||||
- 本机 Podman 网络后端是较老的 **CNI**; 若将来启用 firewalld, `firewall-cmd --reload`
|
||||
可能清掉 Podman 规则, 需要 `podman network reload`;
|
||||
- 换哪条路线, 容器发布的回环端口都不变, Apache 依旧不用改。
|
||||
|
||||
---
|
||||
|
||||
## 14. 附录 B: 二进制 → 容器迁移(已完成, 仅存档)
|
||||
|
||||
本机原有部署是 **Gitea 1.27.3 二进制 + systemd + 宿主 PostgreSQL 18.6**
|
||||
(`ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini`, 监听 `0.0.0.0:2080`)。
|
||||
迁移已于 2026-09-11 完成, 当时用的一次性脚本(`migrate-from-binary.sh` /
|
||||
`install-docker.sh` / `configure-docker-proxy.sh` / `preflight.sh`)已按"一次性"清理掉,
|
||||
过程留档如下。
|
||||
|
||||
**做法**: `systemctl stop gitea` → `rsync` 复制数据(**复制, 不移动**)→
|
||||
`docker compose up -d --build db` 建新集群 → `pg_restore` 灌库并核对表数量 →
|
||||
`up -d gitea` → 验证。源数据与源库全程未改, 因此回滚只需 `docker compose down &&
|
||||
systemctl start gitea`(§9)。
|
||||
|
||||
**当时的迁移前备份**: `deploy/backups/pre-migration-*/`(7 份, 每份含
|
||||
`postgres-giteadb.dump` + `gitea-source-data.tar.gz`)。注意数据包是**宿主布局**,
|
||||
只能 `restore.sh --db-only` 用, 见 §5 的警告。
|
||||
|
||||
### 与宿主 `app.ini` 的**有意**差异
|
||||
|
||||
除"路径改为容器语义"外, 以下是有意为之的行为变化:
|
||||
|
||||
| 配置 | 迁移前 | 现在 | 原因 |
|
||||
|---|---|---|---|
|
||||
| `log.MODE` | `file` | `console` | 日志进 stdout, 用 `docker compose logs` 收集 |
|
||||
| `server.DISABLE_SSH` | `false` | `true` | 实测 `/home/git/.ssh` 不存在, SSH 从未使用; 避免暴露无法工作的克隆地址 |
|
||||
| `server.DOMAIN` | `localhost` | 实际主机/IP | `localhost` 会生成错误的克隆地址; `ROOT_URL` 已显式指定, 此项属修正 |
|
||||
| `security.ALLOWED_HOST_LIST` | `[security]`(**正确**) | **保持 `[security]`** | 1.27 的规范位置就是 `[security]`; `[webhook]` 是 v28.0.0 将移除的 deprecated fallback |
|
||||
| `server.HTTP_ADDR` | `0.0.0.0:2080` | 容器内 `0.0.0.0`, 宿主只发布 `127.0.0.1:2080` | 保持 Apache 反代路径不变, 同时消除直连暴露面 |
|
||||
| `oauth2.ENABLED` | 未设置(默认 `true`) | 显式 `true` | 防止上游改默认值导致漂移 |
|
||||
|
||||
其余配置(注册策略、OIDC 自动注册、admin 限制、pull-request/signing 默认值、
|
||||
`PASSWORD_HASH_ALGO=pbkdf2`、`OFFLINE_MODE`、webhook TLS 等)均按原值 1:1 保留。
|
||||
|
||||
**迁移中发现并处理的既有问题**:
|
||||
|
||||
| # | 问题 | 证据 | 处理 |
|
||||
|---|---|---|---|
|
||||
| 1 | 未设置 `SECRET_KEY` | `/etc/gitea/app.ini` 无该键 | 保持默认, 见 §11 |
|
||||
| 2 | 监听 `0.0.0.0:2080` | `ss -ltn` 显示 `*:2080`; firewalld 未运行 | 容器只发布 `127.0.0.1:2080` |
|
||||
| 3 | `/oidc` 反代指向死端口 | `httpd.conf` 里 `ProxyPass /oidc http://localhost:3000/oidc`, 而 3000 无监听 | IdP 侧问题, 见 §10 |
|
||||
| 4 | 数据目录里留着 amd64 包 | `/var/lib/gitea/gitea-1.26.1-linux-amd64.xz`(本机是 arm64) | 新数据目录不含它 |
|
||||
|
||||
---
|
||||
|
||||
## 15. 文件清单
|
||||
|
||||
```
|
||||
deploy/
|
||||
├── README.md 本文档(部署 / 备份 / 恢复 / 升级)
|
||||
├── compose.yaml 服务定义(版本锁定 / 回环发布 / 环境变量注入配置)
|
||||
├── .env.example 配置模板(复制为 .env)
|
||||
├── db/Dockerfile postgres + zh_CN.UTF-8 locale(版本由 build arg 传入)
|
||||
├── backups/ 备份产物(.gitignore 排除)
|
||||
└── scripts/
|
||||
├── backup.sh 备份: pg_dump + 数据 tar + SHA256SUMS
|
||||
├── restore.sh 恢复: 默认 dry-run, 校验校验和后按备份还原
|
||||
└── verify.sh 体检: 容器健康 + 回环 API + 经 Apache 反代
|
||||
```
|
||||
|
||||
常用命令:
|
||||
|
||||
```bash
|
||||
cd /home/ymy/tjhlp-gitea/deploy
|
||||
|
||||
docker compose config --quiet # 校验 compose 与 .env 插值
|
||||
docker compose up -d --build # 启动 / 应用配置变更
|
||||
docker compose ps && docker compose logs -f --tail=100 gitea
|
||||
|
||||
sudo ./scripts/verify.sh # 体检
|
||||
sudo ./scripts/backup.sh --quiesce # 备份
|
||||
./scripts/restore.sh --list # 看备份
|
||||
sudo ./scripts/restore.sh <时间戳> --apply # 恢复
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 16. 验证状态(诚实声明)
|
||||
|
||||
### 已在本机实测通过(2026-09-11, Rocky 8.10 aarch64)
|
||||
|
||||
- Docker CE 29.8.0 安装(路线 A, `--allowerasing`, podman/runc 已移除);
|
||||
- `docker.service` / `containerd.service` 的代理 drop-in 生效;
|
||||
- `db` 镜像构建成功(`local/gitea-postgres:18.6-zh_CN`);
|
||||
- `db` 容器 `healthy`, `initdb` 带 `--locale=zh_CN.UTF-8` 完成;
|
||||
- `pg_restore` 端到端跑通: **源 116 张表 → 目标 116 张表**;
|
||||
- Gitea 容器 `healthy`, `/api/healthz` 200, `/api/v1/version` = 1.27.3;
|
||||
- 经 Apache `/QA` 反代 200(与迁移前路径一致);
|
||||
- 站点名正确渲染: `<title>Sign In - 同济高程-答疑平台</title>`;
|
||||
- OAuth2/OIDC 登录源 `高程统一身份认证` 注册成功(discovery 200, 登录页出现);
|
||||
- 失败自动回滚(迁移脚本的 EXIT trap)三次实测生效。
|
||||
|
||||
### 本机踩到并已修复的坑
|
||||
|
||||
见 §2 的四个陷阱(postgres:18 挂载点、s6 chown 守卫、`APP_NAME`、代理回环 502),
|
||||
以及验证脚本自身的三个缺陷: 回环探测被 HTTP 代理接管、启动竞态被误报为 FAIL、
|
||||
状态码拼接成 `502000`。
|
||||
|
||||
### 仍未实测
|
||||
|
||||
- `restore.sh --apply` 的完整演练(**只验证了 `--list` 与 dry-run 路径**)——
|
||||
建议尽快照 §6 在测试机上真跑一遍;
|
||||
- `backup.sh` 的 cron 定时执行;
|
||||
- `environment-to-ini` 对含点号 section(如 `GITEA__cron.update_checker__ENABLED`)
|
||||
的处理 —— `conf/app.ini` 已生成且实例工作正常, 但未逐项比对;
|
||||
- PostgreSQL 大版本升级流程(§7.2)—— 步骤按官方文档与 PG18 布局推导, 未实跑;
|
||||
- 重启后"容器自动恢复 + 宿主 unit 已 disable"的组合(建议找时间 `sudo reboot` 验一次)。
|
||||
@@ -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
|
||||
@@ -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'
|
||||
Executable
+88
@@ -0,0 +1,88 @@
|
||||
#!/usr/bin/env bash
|
||||
# =============================================================================
|
||||
# 备份正在运行的 Docker 栈 (PostgreSQL + Gitea 数据)
|
||||
#
|
||||
# ./backup.sh # 在线备份(不中断服务)
|
||||
# ./backup.sh --quiesce # 先停 gitea 容器再备份, 得到一致快照
|
||||
#
|
||||
# 产物: deploy/backups/<时间戳>/
|
||||
# postgres-<db>.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"
|
||||
Executable
+209
@@ -0,0 +1,209 @@
|
||||
#!/usr/bin/env bash
|
||||
# =============================================================================
|
||||
# 从 deploy/backups/<时间戳>/ 恢复 Gitea 数据与 PostgreSQL
|
||||
#
|
||||
# ./scripts/restore.sh --list # 列出可用备份 + 校验状态
|
||||
# ./scripts/restore.sh <时间戳> # dry-run: 只打印恢复计划
|
||||
# sudo ./scripts/restore.sh <时间戳> --apply # 真正执行
|
||||
#
|
||||
# 选项(可与 --apply 组合):
|
||||
# --db-only 只恢复数据库
|
||||
# --data-only 只恢复数据目录
|
||||
# --no-safety-backup 跳过"恢复前先备份当前状态"(不建议)
|
||||
#
|
||||
# 安全设计:
|
||||
# * 默认 dry-run, 只有 --apply 才动手;
|
||||
# * 先校验 SHA256SUMS, 任一文件不匹配立即中止;
|
||||
# * 默认先跑一次 backup.sh --quiesce 保存当前状态, 恢复错了还能退回来;
|
||||
# * 数据目录不做就地覆盖 —— 先把现有目录改名成 <dir>.pre-restore-<时间戳>,
|
||||
# 再解包备份, 因此每一步都能手工回退(结尾会打印回退命令)。
|
||||
# =============================================================================
|
||||
set -euo pipefail
|
||||
|
||||
DEPLOY_DIR=$(cd "$(dirname "$0")/.." && pwd)
|
||||
cd "$DEPLOY_DIR"
|
||||
|
||||
# ---------- 载入 .env(逐行, 不做 shell 展开; $$ 还原为 $)----------
|
||||
[[ -f .env ]] || { echo "错误: 缺少 .env" >&2; exit 1; }
|
||||
while IFS= read -r line || [[ -n "$line" ]]; do
|
||||
[[ "$line" =~ ^[[:space:]]*(#|$) ]] && continue
|
||||
key=${line%%=*}; val=${line#*=}
|
||||
key=${key//[[:space:]]/}
|
||||
[[ "$val" == \"*\" || "$val" == \'*\' ]] && val=${val:1:-1}
|
||||
val=${val//\$\$/\$}
|
||||
export "${key}=${val}"
|
||||
done < .env
|
||||
|
||||
: "${POSTGRES_DB:?}"; : "${POSTGRES_USER:?}"; : "${GITEA_DATA_DIR:?}"
|
||||
GITEA_UID=${GITEA_UID:-982}
|
||||
GITEA_GID=${GITEA_GID:-982}
|
||||
BACKUP_ROOT="${BACKUP_DIR:-$DEPLOY_DIR/backups}"
|
||||
|
||||
DUMP_NAME="postgres-${POSTGRES_DB}.dump"
|
||||
# backup.sh 产出的【容器布局】数据包
|
||||
DATA_NAME="gitea-data.tar.gz"
|
||||
# 二进制部署时期的【宿主布局】数据包。顶层同样是 gitea/, 但内部是
|
||||
# gitea/data/gitea-repositories/... 而容器要的是 gitea/git/repositories/...,
|
||||
# 直接解到 GITEA_DATA_DIR 只会得到一份 Gitea 认不出的目录, 所以必须拒收。
|
||||
SOURCE_DATA_NAME="gitea-source-data.tar.gz"
|
||||
|
||||
die() { echo "错误: $*" >&2; exit 1; }
|
||||
step() { echo; echo "==> $*"; }
|
||||
|
||||
# ---------- 参数 ----------
|
||||
MODE_LIST=0; APPLY=0; DO_DB=1; DO_DATA=1; SAFETY=1; STAMP=""
|
||||
for a in "$@"; do
|
||||
case "$a" in
|
||||
--list) MODE_LIST=1 ;;
|
||||
--apply) APPLY=1 ;;
|
||||
--db-only) DO_DATA=0 ;;
|
||||
--data-only) DO_DB=0 ;;
|
||||
--no-safety-backup) SAFETY=0 ;;
|
||||
-h|--help) sed -n '2,20p' "$0"; exit 0 ;;
|
||||
-*) echo "未知参数: $a" >&2; exit 2 ;;
|
||||
*) STAMP="$a" ;;
|
||||
esac
|
||||
done
|
||||
|
||||
list_backups() {
|
||||
[[ -d "$BACKUP_ROOT" ]] || { echo "备份目录不存在: $BACKUP_ROOT"; return 0; }
|
||||
printf '%-26s %-6s %-7s %-7s %s\n' "时间戳" "校验" "大小" "数据库" "数据目录"
|
||||
local d name chk size db data
|
||||
for d in "$BACKUP_ROOT"/*/; do
|
||||
[[ -d "$d" ]] || continue
|
||||
name=$(basename "$d")
|
||||
if [[ -f "$d/SHA256SUMS" ]]; then
|
||||
if (cd "$d" && sha256sum -c --status SHA256SUMS) 2>/dev/null; then chk="ok"; else chk="损坏"; fi
|
||||
else
|
||||
chk="-"
|
||||
fi
|
||||
size=$(du -sh "$d" 2>/dev/null | cut -f1)
|
||||
if [[ -f "$d/$DUMP_NAME" ]]; then db="有"; else db="-"; fi
|
||||
if [[ -f "$d/$DATA_NAME" ]]; then data="容器布局"
|
||||
elif [[ -f "$d/$SOURCE_DATA_NAME" ]]; then data="宿主布局, 不可直接恢复"
|
||||
else data="-"; fi
|
||||
printf '%-26s %-6s %-7s %-7s %s\n' "$name" "$chk" "$size" "$db" "$data"
|
||||
done
|
||||
}
|
||||
|
||||
if [[ $MODE_LIST -eq 1 ]]; then
|
||||
echo "备份目录: $BACKUP_ROOT"
|
||||
echo
|
||||
list_backups
|
||||
exit 0
|
||||
fi
|
||||
|
||||
if [[ -z "$STAMP" ]]; then
|
||||
echo "已有一份备份清单如下 —— 请把时间戳作为参数传给本脚本。" >&2
|
||||
echo >&2
|
||||
list_backups >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
SRC="$BACKUP_ROOT/$STAMP"
|
||||
[[ -d "$SRC" ]] || die "找不到备份目录: $SRC"
|
||||
[[ -f "$SRC/SHA256SUMS" ]] || die "缺少 $SRC/SHA256SUMS(无法校验完整性)"
|
||||
[[ $DO_DB -eq 0 || -f "$SRC/$DUMP_NAME" ]] || die "缺少 $SRC/$DUMP_NAME"
|
||||
if [[ $DO_DATA -eq 1 && ! -f "$SRC/$DATA_NAME" ]]; then
|
||||
if [[ -f "$SRC/$SOURCE_DATA_NAME" ]]; then
|
||||
cat >&2 <<EOF
|
||||
错误: 该备份里的数据包是 $SOURCE_DATA_NAME —— 二进制部署时期的【宿主布局】备份
|
||||
(内含 gitea/data/gitea-repositories/...), 与容器要求的 gitea/git/repositories/... 不同,
|
||||
不能直接解到 $GITEA_DATA_DIR。
|
||||
|
||||
只想恢复数据库: 加 --db-only
|
||||
想回滚到二进制: docker compose down && sudo systemctl start gitea(源数据仍在 /var/lib/gitea)
|
||||
想要容器布局备份: ./scripts/backup.sh 生成一份新的
|
||||
EOF
|
||||
exit 1
|
||||
fi
|
||||
die "缺少 $SRC/$DATA_NAME"
|
||||
fi
|
||||
|
||||
step "校验备份完整性"
|
||||
(cd "$SRC" && sha256sum -c SHA256SUMS)
|
||||
|
||||
step "恢复计划"
|
||||
cat <<EOF
|
||||
来源 : $SRC
|
||||
数据库 : $( [[ $DO_DB -eq 1 ]] && echo "$POSTGRES_DB <- $DUMP_NAME (pg_restore --clean --if-exists)" || echo "跳过" )
|
||||
数据目录 : $( [[ $DO_DATA -eq 1 ]] && echo "$GITEA_DATA_DIR <- $DATA_NAME ($(du -h "$SRC/$DATA_NAME" | cut -f1))" || echo "跳过" )
|
||||
恢复前备份 : $( [[ $SAFETY -eq 1 ]] && echo "会执行 ./scripts/backup.sh --quiesce" || echo "跳过(--no-safety-backup)" )
|
||||
数据目录处理 : 现有目录改名 ${GITEA_DATA_DIR}.pre-restore-<时间戳> 后解包(不删除)
|
||||
EOF
|
||||
|
||||
if [[ $APPLY -eq 0 ]]; then
|
||||
echo
|
||||
echo "==> 这是 dry-run, 未做任何改动。确认无误后加 --apply 执行。"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
[[ $EUID -eq 0 ]] || die "--apply 需要 root(读写 $GITEA_DATA_DIR、chown、访问 docker)"
|
||||
|
||||
if [[ $SAFETY -eq 1 ]]; then
|
||||
step "保存当前状态(恢复失败时的退路)"
|
||||
./scripts/backup.sh --quiesce
|
||||
fi
|
||||
|
||||
step "确保 db 容器在运行"
|
||||
docker compose up -d db
|
||||
DB_CID=$(docker compose ps -q db)
|
||||
[[ -n "$DB_CID" ]] || die "拿不到 db 容器 id"
|
||||
h=""
|
||||
for _ in $(seq 1 24); do
|
||||
h=$(docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{end}}' "$DB_CID" 2>/dev/null || echo "")
|
||||
[[ "$h" == "healthy" ]] && break
|
||||
sleep 5
|
||||
done
|
||||
[[ "$h" == "healthy" ]] || die "db 容器未变为 healthy(当前: ${h:-未知})"
|
||||
echo " db: healthy"
|
||||
|
||||
step "停止 gitea 容器"
|
||||
docker compose stop gitea
|
||||
|
||||
PRE="${GITEA_DATA_DIR}.pre-restore-$(date +%Y%m%d-%H%M%S)"
|
||||
if [[ $DO_DATA -eq 1 ]]; then
|
||||
step "恢复数据目录"
|
||||
mv "$GITEA_DATA_DIR" "$PRE"
|
||||
mkdir -p "$(dirname "$GITEA_DATA_DIR")"
|
||||
tar -C "$(dirname "$GITEA_DATA_DIR")" -xzf "$SRC/$DATA_NAME"
|
||||
chown -R "${GITEA_UID}:${GITEA_GID}" "$GITEA_DATA_DIR"
|
||||
echo " 解包完成, 属主已设为 ${GITEA_UID}:${GITEA_GID}"
|
||||
echo " 旧目录保留在: $PRE"
|
||||
fi
|
||||
|
||||
if [[ $DO_DB -eq 1 ]]; then
|
||||
step "恢复数据库 $POSTGRES_DB"
|
||||
if docker compose exec -T db pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" \
|
||||
--clean --if-exists --no-owner < "$SRC/$DUMP_NAME"; then
|
||||
echo " pg_restore 完成"
|
||||
else
|
||||
echo " ⚠️ pg_restore 返回非 0 —— 请检查上面的输出。" >&2
|
||||
echo " 常见无害项: 'does not exist, skipping'。仍以表数量与 verify.sh 为准。" >&2
|
||||
fi
|
||||
echo " public schema 表数量: $(docker compose exec -T db psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" \
|
||||
-tAc "select count(*) from information_schema.tables where table_schema='public'")"
|
||||
fi
|
||||
|
||||
step "启动 gitea"
|
||||
docker compose up -d gitea
|
||||
G_CID=$(docker compose ps -q gitea)
|
||||
gh=""
|
||||
for _ in $(seq 1 24); do
|
||||
gh=$(docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{end}}' "$G_CID" 2>/dev/null || echo "")
|
||||
[[ "$gh" == "healthy" ]] && break
|
||||
sleep 5
|
||||
done
|
||||
echo " gitea: ${gh:-未知}"
|
||||
|
||||
step "验证"
|
||||
./scripts/verify.sh || true
|
||||
|
||||
echo
|
||||
echo "==> 恢复结束"
|
||||
if [[ $DO_DATA -eq 1 ]]; then
|
||||
echo "若数据目录恢复错了, 回退:"
|
||||
echo " sudo docker compose stop gitea"
|
||||
echo " sudo rm -rf '$GITEA_DATA_DIR' && sudo mv '$PRE' '$GITEA_DATA_DIR'"
|
||||
echo " sudo docker compose start gitea"
|
||||
fi
|
||||
Executable
+120
@@ -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
|
||||
Reference in New Issue
Block a user