SHA256
forked from course-team/tjhlp-gitea
Compare commits
21
Commits
20d6d7eef5
...
main
| Author | SHA256 | Date | |
|---|---|---|---|
|
|
9446850182 | ||
|
|
8d5c8c6bae | ||
|
|
53116f7a23 | ||
|
|
1272c1ebec | ||
|
|
487c9e8726 | ||
|
|
787481c2c8 | ||
|
|
7ff17f8b2a | ||
|
|
99547005bd | ||
|
|
438c0f4e01 | ||
|
|
c5fdbe16d6 | ||
|
|
77b9e72388 | ||
|
|
73ce8162aa | ||
|
|
ea3ad2bb31 | ||
|
|
a65970303f | ||
|
|
b60e5e9f1e | ||
|
|
25f1ec6cfc | ||
|
|
e489d19cb6 | ||
|
|
68fb567cb3 | ||
|
|
44b174d319 | ||
|
|
7d19e2729c | ||
|
|
79256c5be0 |
@@ -0,0 +1,54 @@
|
||||
# main 推送后自动部署到 10.80.42.185/QA。
|
||||
# 逻辑都在 deploy/scripts/auto-deploy.sh 里, 这里只负责"同步到目标提交 + 调脚本"。
|
||||
# 详见 deploy/ci-cd.md。
|
||||
name: deploy
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
workflow_dispatch:
|
||||
|
||||
concurrency:
|
||||
group: deploy-main
|
||||
cancel-in-progress: false
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
# 只认 main 的 push 或手动触发; 提交信息含 [skip deploy] 则跳过
|
||||
if: >-
|
||||
github.event_name == 'workflow_dispatch' ||
|
||||
(github.ref == 'refs/heads/main' &&
|
||||
!contains(github.event.head_commit.message, '[skip deploy]'))
|
||||
runs-on: self-hosted
|
||||
timeout-minutes: 30
|
||||
# ★ 宿主能力(docker socket、部署克隆、裸库、docker CLI)由【本 job】申报,而不是由
|
||||
# runner 全局发给每个 job。runner 侧的 container.valid_volumes 是允许清单:
|
||||
# 没列进去的挂载会被丢弃,所以这里的每一项都要在 deploy/runner/config.yaml 里有对应项。
|
||||
# 将来加 PR 检查/测试 workflow 时,那个 job 不申报就什么都拿不到(无 socket = 无 root)。
|
||||
container:
|
||||
volumes:
|
||||
- /home/ymy/deploy:/home/ymy/deploy # 工作目录(auto-deploy.sh 要写 .state)
|
||||
- /srv/gitea:/srv/gitea:ro # deploy 克隆的 origin(本地裸库)
|
||||
- /var/run/docker.sock:/var/run/docker.sock # docker compose up -d
|
||||
- /usr/bin/docker:/usr/bin/docker:ro # 宿主 docker CLI
|
||||
- /usr/libexec/docker/cli-plugins:/usr/libexec/docker/cli-plugins:ro # compose 插件
|
||||
steps:
|
||||
- name: 同步到目标提交
|
||||
run: |
|
||||
set -euo pipefail
|
||||
cd /home/ymy/deploy/tjhlp-gitea
|
||||
git fetch --prune origin
|
||||
# -f: 部署克隆是 CI 独占的; 上一个已部署版本的 deploy/runner/* 等文件在本版本
|
||||
# 若已被跟踪, 会作为"未跟踪文件"挡住普通 checkout(实测)
|
||||
git checkout -f --detach "${{ github.sha }}"
|
||||
git --no-pager log --oneline -1
|
||||
- name: 构建并部署(失败自动回滚)
|
||||
run: |
|
||||
set -euo pipefail
|
||||
# 工作流没有 actions/checkout, 默认工作目录里没有代码; 上一步已把
|
||||
# 部署克隆同步到目标提交, 这里必须显式 cd 过去 (2026-09-21 实际踩到)。
|
||||
cd /home/ymy/deploy/tjhlp-gitea
|
||||
./deploy/scripts/auto-deploy.sh
|
||||
+11
-2
@@ -14,8 +14,17 @@ credentials_*.csv
|
||||
*.pem
|
||||
*.key
|
||||
|
||||
# Ansible
|
||||
*.retry
|
||||
# Deployment (docker compose)
|
||||
deploy/.env
|
||||
deploy/backups/
|
||||
# CI/CD: 部署状态(上次成功的 SHA)与 runner 的注册凭据/缓存
|
||||
deploy/.state/
|
||||
deploy/runner/.env
|
||||
deploy/runner/data/
|
||||
|
||||
# Customization
|
||||
customization/custom/options/locale/locale_zh-CN.json
|
||||
customization/preview/data/
|
||||
|
||||
# IDE
|
||||
.idea/
|
||||
|
||||
@@ -17,7 +17,8 @@
|
||||
|
||||
```text
|
||||
tjhlp-gitea/
|
||||
├── ansible/ Ansible 自动化部署(Gitea + PostgreSQL)
|
||||
├── deploy/ Docker 部署与运维(Gitea + PostgreSQL)
|
||||
├── customization/ Gitea 客制化(首页、中文术语、去 Gitea 化)与本地预览
|
||||
├── issue-templates/ Issue 模板(按仓库类型区分)
|
||||
└── scripts/ Python CLI 管理工具
|
||||
```
|
||||
@@ -26,16 +27,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 +102,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 验证
|
||||
@@ -114,17 +117,31 @@ ansible-lint playbook.yml # 最佳实践
|
||||
yamllint issue-templates/ # YAML 语法
|
||||
```
|
||||
|
||||
### 定制(Gitea 客制化)
|
||||
|
||||
```bash
|
||||
python3 customization/build.py # 生成定制语言文件
|
||||
python3 customization/build.py --check # 校验生成物是否最新
|
||||
customization/preview/preview.sh up # 起本地预览(127.0.0.1:2081)
|
||||
customization/preview/preview.sh semester # 造一个学期组织, 看首页答疑入口卡片
|
||||
customization/preview/preview.sh check # 自动校验首页/登录页/卡片/页脚/meta/术语
|
||||
```
|
||||
|
||||
机制调查、日常改法与部署/升级流程见 [`customization/README.md`](customization/README.md);
|
||||
与课程官网(<https://cpp.tongji.sh/Website/>)的互相导流见
|
||||
[`customization/website-linkage.md`](customization/website-linkage.md)。
|
||||
|
||||
详见各子目录的 README。
|
||||
|
||||
## 技术栈
|
||||
|
||||
| 组件 | 技术选型 |
|
||||
| ------ | ---------- |
|
||||
| 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,379 @@
|
||||
# TJHLP 定制(Gitea 客制化)
|
||||
|
||||
本目录存放课程答疑平台对 Gitea 的定制:**不改 Go 代码、不 fork、不重新编译**,
|
||||
只通过 Gitea 官方的 `CustomPath` 覆盖机制 + `app.ini` 配置项来做。
|
||||
|
||||
- 首页从「一款极易搭建的自托管 Git 服务」改成答疑平台介绍
|
||||
- 中文术语调整(Issue 不再译成「工单」等)
|
||||
- 去掉 Gitea 的自我推销(页脚 Powered by、meta、docs.gitea.com 外链)
|
||||
|
||||
当前基线:**Gitea 1.27.3**(见 `gitea-version.txt`,需与 `deploy/.env` 的
|
||||
`GITEA_VERSION` 保持一致)。
|
||||
|
||||
---
|
||||
|
||||
## 1. 调查结论(机制)
|
||||
|
||||
以下结论来自 1.27.3 源码与实机验证,不是猜测。
|
||||
|
||||
### 1.1 覆盖原理:CustomPath 分层文件系统
|
||||
|
||||
Gitea 把模板 / 语言 / 静态资源都编进了二进制,但读取时走 `assetfs.LayeredFS`:
|
||||
**自定义层在前、内置层在后,同名文件自定义层优先**;不存在「部分合并」——
|
||||
覆盖一个文件就是整份替换(`modules/assetfs/layered.go`)。
|
||||
|
||||
| 内容 | 自定义层路径 | 内置层 | 生效方式 |
|
||||
| ------ | -------------- | -------- | ---------- |
|
||||
| 页面模板 | `$CustomPath/templates/<相对路径>` | 二进制内 embed | 启动时编译,**重启生效** |
|
||||
| 语言文件 | `$CustomPath/options/locale/locale_*.json` | 二进制内 embed | 启动时加载,dev 模式热加载 |
|
||||
| 静态资源 | `$CustomPath/public/assets/**` | 二进制内 embed | 请求时读取,URL 前缀 `/assets/` |
|
||||
| 其它数据 | `$CustomPath/options/{gitignore,label,license,readme}/...` | 二进制内 embed | 按需读取 |
|
||||
|
||||
> ★ **最容易踩的坑**:官方 Docker 镜像里 `GITEA_CUSTOM=/data/gitea`
|
||||
> (`docker inspect` 可见),所以定制文件对应的是
|
||||
> `/data/gitea/{templates,public,options}`,
|
||||
> **不是** `/data/gitea/custom/...`。后者是「源码/二进制安装时
|
||||
> `WorkPath/custom`」的习惯写法,在容器里挂了不会生效(实测无效)。
|
||||
|
||||
### 1.2 模板
|
||||
|
||||
- 落地页是 `templates/home.tmpl`;登录用户看到的是 Dashboard,落地页只对**未登录访客**
|
||||
渲染(`routers/web/home.go`)。
|
||||
- 想换首页有三种做法,成本从低到高:
|
||||
1. **配置**:`[server] LANDING_PAGE = explore|organizations|login|/任意URL`
|
||||
—— 直接不做落地页;
|
||||
2. **模板**:覆盖 `custom/templates/home.tmpl`(本目录采用的做法);
|
||||
3. 加导航/页脚链接不需要覆盖整文件,用 `custom/templates/custom/extra_links.tmpl`、
|
||||
`extra_links_footer.tmpl`(内置就是空模板,属增量修改)。
|
||||
- 模板在**启动时编译**:prod 下改完必须重启容器(官方文档同此说法)。
|
||||
dev 模式会尝试热加载,但实测模板热加载不生效(语言文件可以),所以模板统一按
|
||||
「改完重启」处理。
|
||||
- 覆盖模板时**不要动 `{{...}}` 逻辑**,只改文案/图标/链接;上游升级后要 diff 回来。
|
||||
|
||||
### 1.3 中文翻译
|
||||
|
||||
- 1.27 起语言文件是 JSON(`options/locale/locale_zh-CN.json`,约 3900 个键)。
|
||||
- 覆盖必须**整份文件**:非默认语言在加载时没有 en-US 兜底基座,而查不到键时会
|
||||
**退回默认语言(英文)**,不是退回中文
|
||||
(`modules/translation/translation.go`、`i18n/localestore.go`)。
|
||||
只写几个键会导致整个界面大面积变英文。
|
||||
- 因此本目录用 `build.py` 从**上游快照 + 我们的覆盖规则**确定性生成整份文件,
|
||||
人只需要维护 `overrides/` 下那几十行(详见 §3)。
|
||||
|
||||
### 1.4 能用配置解决的,别动模板
|
||||
|
||||
| 目标 | 配置项(app.ini) | Docker 环境变量 |
|
||||
| ------ | ----------------- | ----------------- |
|
||||
| 站点名 | 顶层 `APP_NAME` | `APP_NAME`(裸变量,镜像模板用) |
|
||||
| 首页指向 | `[server] LANDING_PAGE` | `GITEA__server__LANDING_PAGE` |
|
||||
| meta 作者/描述/关键词 | `[ui.meta] AUTHOR/DESCRIPTION/KEYWORDS` | `GITEA__ui_0X2E_meta__DESCRIPTION` 等 |
|
||||
| 页脚 Powered by / 版本号 | `[other] SHOW_FOOTER_POWERED_BY` / `SHOW_FOOTER_VERSION` | `GITEA__other__SHOW_FOOTER_POWERED_BY` |
|
||||
| Issue 显示姓名而非学号 | `[ui] DEFAULT_SHOW_FULL_NAME` | `GITEA__ui__DEFAULT_SHOW_FULL_NAME` |
|
||||
| 自定义主题配色 | `[ui] THEMES` + `custom/public/assets/css/theme-*.css` | `GITEA__ui__THEMES` |
|
||||
| 关闭通行密钥(WebAuthn) | `[service] ENABLE_PASSKEY_AUTHENTICATION` | `GITEA__service__ENABLE_PASSKEY_AUTHENTICATION` |
|
||||
| 关闭用户名/密码表单 | `[service] ENABLE_PASSWORD_SIGNIN_FORM` | `GITEA__service__ENABLE_PASSWORD_SIGNIN_FORM` |
|
||||
| Logo / favicon | 放 `custom/public/assets/img/{logo,favicon}.svg` 等 | 同上(文件方式) |
|
||||
|
||||
> 环境变量规则:`GITEA__<段名>__<键名>`,段名里的 `.` 不能直接写,要编码成
|
||||
> `_0X2E_`,所以 `[ui.meta]` 是 `GITEA__ui_0X2E_meta__...`
|
||||
> (`modules/setting/config_env.go`)。
|
||||
|
||||
### 1.5 选择顺序(重要)
|
||||
|
||||
改一个东西之前,按这个顺序选手段,维护成本递增:
|
||||
|
||||
1. **app.ini / 环境变量**(无文件、升级无感)
|
||||
2. **`custom/templates/custom/extra_*.tmpl`**(增量追加,不覆盖上游文件)
|
||||
3. **`custom/options/` 数据文件覆盖**(语言、labels…)
|
||||
4. **整文件覆盖内置模板**(本目录的 `custom/templates/home.tmpl`、`base/head_navbar.tmpl`)
|
||||
5. 自建镜像 / fork 改 Go 代码 —— 只有在需要改逻辑或前端资源时才考虑,本阶段不需要
|
||||
|
||||
---
|
||||
|
||||
## 2. 目录结构
|
||||
|
||||
```text
|
||||
customization/
|
||||
├── README.md 本文件
|
||||
├── gitea-version.txt 基线版本(与 deploy/.env 的 GITEA_VERSION 同步)
|
||||
├── build.py 生成 locale + 规范 custom/ 权限(容器用户要能读)
|
||||
├── fetch-upstream.sh 拉取上游文件快照(升级时用)
|
||||
├── upstream-files.txt 需要留快照的上游文件清单
|
||||
├── upstream/<版本>/... 上游基线,只读参考,由脚本生成
|
||||
├── overrides/ ★ 只维护这里
|
||||
│ ├── locale_zh-CN.rules.json 批量字面替换(如「工单」→「Issue」)
|
||||
│ └── locale_zh-CN.json 精确到键的覆盖(优先于 rules)
|
||||
├── custom/ ★ 挂进容器的覆盖层(= $CustomPath 的内容)
|
||||
│ ├── templates/home.tmpl 落地页
|
||||
│ ├── templates/base/head_navbar.tmpl 导航栏(去掉 docs.gitea.com)
|
||||
│ ├── templates/user/auth/signin.tmpl 登录页(统一身份认证优先, 管理员登录次要)
|
||||
│ ├── templates/user/dashboard/dashboard.tmpl 首页(登录后); 只比上游多一行 include
|
||||
│ ├── templates/custom/tjhlp_semester_card.tmpl ★ 首页顶部的学期答疑入口卡片(自己写的)
|
||||
│ ├── public/.gitkeep 占位(提问指南已只在官网, 目录留作将来放静态资源)
|
||||
│ └── options/locale/locale_zh-CN.json 生成物,已 gitignore
|
||||
└── preview/ 本地预览(独立 compose,独立端口/数据)
|
||||
├── compose.yaml
|
||||
├── preview.sh
|
||||
└── data/ 预览数据,已 gitignore
|
||||
```
|
||||
|
||||
`custom/` 与 `$CustomPath` 的结构一一对应;`custom/options/locale/*.json` 是生成物,
|
||||
**不要手改**(`build.py --check` 会检查是否与 overrides 一致)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 改东西的日常流程
|
||||
|
||||
### 3.1 改中文翻译
|
||||
|
||||
只动 `overrides/`,然后重新生成:
|
||||
|
||||
```bash
|
||||
# 批量术语: 改 overrides/locale_zh-CN.rules.json
|
||||
# 个例精修: 改 overrides/locale_zh-CN.json(键必须在同版本上游存在,否则构建报错)
|
||||
python3 customization/build.py # 会打印每一处改动
|
||||
python3 customization/build.py --check # CI/部署前校验生成物是否最新
|
||||
```
|
||||
|
||||
约定:
|
||||
|
||||
- `rules` 是字面替换,会自动在中英交界处补空格(`基于工单列表` → `基于 Issue 列表`);
|
||||
- `overrides` 在 rules 之后应用,用来收拾生硬的地方(如 `<strong>%d</strong> 张工单`
|
||||
→ `共 <strong>%d</strong> 个 Issue`);
|
||||
- 含占位符(`%s`/`%[1]s`/`%d`)的条目会校验占位符是否被改坏,改坏直接构建失败;
|
||||
- 覆盖键在上游不存在会报错 —— 这是升级时发现「上游删了/改了键名」的保护。
|
||||
|
||||
### 3.2 改页面
|
||||
|
||||
1. 先把上游基线 diff 一遍,确认结构没变:
|
||||
`diff upstream/<版本>/templates/home.tmpl custom/templates/home.tmpl`
|
||||
2. 在 `custom/templates/...` 里改文案/图标/链接;
|
||||
3. 新增一个要覆盖的模板时,把它加进 `upstream-files.txt`,再跑
|
||||
`customization/fetch-upstream.sh <版本>` 留下基线。
|
||||
|
||||
### 3.3 本地预览
|
||||
|
||||
```bash
|
||||
customization/preview/preview.sh up # 启动,http://127.0.0.1:2081
|
||||
customization/preview/preview.sh logs # 看日志
|
||||
customization/preview/preview.sh reload # 改完模板/生成语言文件后重启
|
||||
customization/preview/preview.sh check # 自动校验: 首页文案/页脚/meta/静态页/术语
|
||||
customization/preview/preview.sh admin # 建管理员(验证登录后页面,如 Issue 列表)
|
||||
customization/preview/preview.sh reset # 清空预览数据重新来
|
||||
```
|
||||
|
||||
预览实例与生产完全隔离:项目名 `gitea-preview`、容器 `gitea-preview`、
|
||||
端口只绑 `127.0.0.1:2081`、数据库用 sqlite、数据在 `preview/data/`(删掉即重置)。
|
||||
用的是**与生产相同的镜像版本**,所以渲染结果一致。
|
||||
|
||||
- `RUN_MODE` 默认 `dev`:语言文件改动会自动热加载(实测),模板报错也不致命;
|
||||
`PREVIEW_RUN_MODE=prod ./preview.sh up` 可切到与生产一致的严格模式。
|
||||
- **模板改动仍需重启**(`reload`),这是 Gitea 的既有行为。
|
||||
- 需要 docker 权限;当前 shell 不在 docker 组时脚本会自动改用 `sg docker -c`。
|
||||
|
||||
### 3.4 登录页
|
||||
|
||||
登录页 `custom/templates/user/auth/signin.tmpl` 的结构是「统一身份认证(第一张卡) +
|
||||
管理员登录(第二张卡)」,认证源那部分直接复用上游的
|
||||
`{{template "user/auth/external_auth_methods" .}}`,所以**换认证源不用改模板**。
|
||||
|
||||
预览实例默认没有配置任何认证源,登录页就只显示管理员卡片。想看到统一身份认证那张卡,
|
||||
临时加一个认证源即可(用完删掉):
|
||||
|
||||
```bash
|
||||
# 加: 用 github 这类不需要 discovery 的 provider 最省事, 只为看布局
|
||||
sg docker -c "docker exec -u git gitea-preview gitea admin auth add-oauth \
|
||||
--name '高程统一身份认证(测试)' --provider github --key k --secret s"
|
||||
sg docker -c 'docker exec -u git gitea-preview gitea admin auth list' # 看 ID
|
||||
sg docker -c 'docker exec -u git gitea-preview gitea admin auth delete --id 1'
|
||||
```
|
||||
|
||||
**通行密钥(WebAuthn)已关闭**,不是靠模板删的,而是配置:
|
||||
`[service] ENABLE_PASSKEY_AUTHENTICATION = false`(两处 compose 都设了)。
|
||||
上游那块在浏览器不支持条件中介时会渲染成一个空的方框,关掉配置连区块都不再输出。
|
||||
|
||||
### 3.5 首页(登录后)的「本学期答疑入口」卡片
|
||||
|
||||
登录后首页上游会给贡献热力图、最近活动、仓库列表, 对只来提问的同学是干扰。
|
||||
我们在页面顶部加了一张约 1/3 屏高的卡片, 里面一个按钮直接跳到本学期答疑区。
|
||||
|
||||
涉及两个文件:
|
||||
|
||||
| 文件 | 作用 |
|
||||
|---|---|
|
||||
| `custom/templates/user/dashboard/dashboard.tmpl` | 覆盖上游同名模板, **只比上游多一行** `{{template "custom/tjhlp_semester_card" .}}`(插在 navbar 之后、`flex-container` 之前) |
|
||||
| `custom/templates/custom/tjhlp_semester_card.tmpl` | 卡片本身(本课程自己写的, 上游没有这个文件) |
|
||||
|
||||
判定与规则(都在卡片文件里, 改它就行):
|
||||
|
||||
- 数据来自 `.Orgs` —— 当前登录用户所属的全部组织(`routers/web/user/home.go` 的 Dashboard 注入);
|
||||
- 「学期组织」= 名字形如 `tjhlp-<5 位数字>`: `tjhlp-26271` 表示 26|27|1 →
|
||||
2026-2027 学年第一学期; 旧命名 `tjhlp-2026s`(带字母)不认, 其它前缀(`course-team`)也不认;
|
||||
- 同时匹配多个时取**名字最大**的(即最新学期), 所以同学同时在上学期/本学期组织里也只会看到本学期;
|
||||
- 按钮指向 `{{AppSubUrl}}/<学期组织>/general/issues`
|
||||
—— 依赖「每个学期组织都有一个 `general` 仓库」这个约定(`tjhlp setup init` 会建);
|
||||
- 一个都匹配不上就**整张卡片不显示**(宁可不显示, 也不给同学一个错的入口)。
|
||||
|
||||
预览里怎么看:
|
||||
|
||||
```bash
|
||||
./preview.sh admin # 先有管理员(仅首次)
|
||||
./preview.sh semester # 建 tjhlp-26271 + general 仓库, 创建者即成员
|
||||
# 想验证筛选规则, 再建几个干扰项: 旧的 tjhlp-25261 / 带字母的 tjhlp-2026s
|
||||
./preview.sh semester previewadmin previewadmin123 tjhlp-2026s
|
||||
# 然后浏览器登录 http://127.0.0.1:2081 (previewadmin / previewadmin123) 看首页
|
||||
```
|
||||
|
||||
`./preview.sh check` 会自动登录 previewadmin 抓一次首页, 断言卡片存在、按钮指向
|
||||
`<学期组织>/general/issues`、高度是 `33vh`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 纳入当前项目 & 部署
|
||||
|
||||
### 4.1 改动点(已在 `deploy/` 落地)
|
||||
|
||||
`deploy/compose.yaml` 的 `gitea` 服务增加了三行只读挂载(注意目标是
|
||||
`/data/gitea/...`,不是 `/data/gitea/custom/...`),`deploy/.env` 与
|
||||
`.env.example` 增加了 `GITEA_CUSTOM_DIR=../customization/custom`:
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- ${GITEA_DATA_DIR:?GITEA_DATA_DIR is required}:/data
|
||||
# 定制覆盖层: 官方镜像 GITEA_CUSTOM=/data/gitea
|
||||
- ${GITEA_CUSTOM_DIR:?GITEA_CUSTOM_DIR is required}/templates:/data/gitea/templates:ro
|
||||
- ${GITEA_CUSTOM_DIR:?GITEA_CUSTOM_DIR is required}/public:/data/gitea/public:ro
|
||||
- ${GITEA_CUSTOM_DIR:?GITEA_CUSTOM_DIR is required}/options:/data/gitea/options:ro
|
||||
```
|
||||
|
||||
`deploy/.env` 增加:
|
||||
|
||||
```ini
|
||||
# 相对 deploy/ 目录解析; 也可写绝对路径
|
||||
GITEA_CUSTOM_DIR=../customization/custom
|
||||
```
|
||||
|
||||
再在 `gitea` 的 `environment:` 里补上去 Gitea 化的元信息(也可以只改 `APP_NAME`):
|
||||
|
||||
```yaml
|
||||
GITEA__ui_0X2E_meta__AUTHOR: 同济大学高级语言程序设计课程
|
||||
GITEA__ui_0X2E_meta__DESCRIPTION: 同济大学高级语言程序设计课程答疑平台
|
||||
GITEA__ui_0X2E_meta__KEYWORDS: 同济大学,高级语言程序设计,答疑,Issue
|
||||
GITEA__other__SHOW_FOOTER_POWERED_BY: "false"
|
||||
GITEA__other__SHOW_FOOTER_VERSION: "false"
|
||||
# Issue 发布者/评论者显示姓名(导入时 full_name=姓名, login=学号)
|
||||
GITEA__ui__DEFAULT_SHOW_FULL_NAME: "true"
|
||||
```
|
||||
|
||||
设计取舍:
|
||||
|
||||
- **只读挂载**:定制内容是仓库里的源码,容器不应回写;`conf/`、`log/` 等仍在
|
||||
`/data/gitea` 里由容器自己管理,互不影响。
|
||||
- 挂三个子目录而不是整个 `custom/`:避免遮住同级的 `conf/`、`log/`。
|
||||
- 镜像 entrypoint 会做 `chown -R git:git /data/gitea`,只在属主不是 `git` 时执行;
|
||||
现有 `/srv/gitea/gitea` 属主已是 `git`(982),不会碰到只读挂载。
|
||||
- 定制只影响渲染,**不碰数据库和仓库**,回滚 = 去掉挂载 + 重启。
|
||||
|
||||
### 4.2 与课程官网联动
|
||||
|
||||
课程官网(VitePress 项目 `tjhlp-website`,部署在同一台机器的 `https://cpp.tongji.sh/Website/`)
|
||||
与答疑平台互为入口。平台侧已经落地的入口:
|
||||
|
||||
| 位置 | 内容 | 文件 |
|
||||
| ------ | ------ | ------ |
|
||||
| 导航栏(未登录) | 「课程官网」/「提问指南」 | `custom/templates/base/head_navbar.tmpl` |
|
||||
| 用户菜单(已登录) | 「课程官网」/「提问指南」 | 同上 |
|
||||
| 首页「按模板提问」卡片 | 官网《提问指南》 | `custom/templates/home.tmpl` |
|
||||
| 首页底部「相关站点」 | 官网 / 提问指南 / 常见问题 / 联系我们 | 同上 |
|
||||
| 首页答疑入口卡片 | 官网《提问指南》 | `custom/templates/custom/tjhlp_semester_card.tmpl` |
|
||||
| 新建 Issue 页的引导链接 | 提问指南 / 课程官网 | `issue-templates/*/.gitea/ISSUE_TEMPLATE/config.yaml` |
|
||||
|
||||
官网地址 `https://cpp.tongji.sh/Website/` 出现在上表列出的模板与两个 `config.yaml` 里;
|
||||
平台自身地址只在 `scripts/settings.toml` 的 `gitea.public_url` 里维护一处(Issue 模板里的
|
||||
`{{BASE_URL}}` 在推送时替换)。
|
||||
|
||||
> **提问指南只在官网保留一份**(`/Website/qa/ask/`):平台内原来的副本
|
||||
> `custom/public/assets/tjhlp/ask-guide.html` 已在 2026-09 删除, 相关链接全部指向官网。
|
||||
> 官网 2026-09 改版后的路径: 提问指南 `/Website/qa/ask/`、常见问题 `/Website/qa/faq/`、
|
||||
> 联系我们 `/Website/contact.html`; 旧的 `/Website/ask-question/`、`/Website/faq/`
|
||||
> 只是跳转页, `/Website/contact` 已经 404 —— 不要再写这些旧地址。
|
||||
|
||||
反向的入口(官网 → 平台)在 Website 仓库里,方案见
|
||||
[`website-linkage.md`](website-linkage.md)。
|
||||
|
||||
### 4.3 部署步骤
|
||||
|
||||
```bash
|
||||
cd deploy
|
||||
python3 ../customization/build.py # 1. 重新生成 + 规范 custom/ 权限(见下)
|
||||
python3 ../customization/build.py --check # (可选)校验生成物与权限
|
||||
./scripts/backup.sh # 2. 例行备份(内容定制其实不影响数据)
|
||||
# 3. 应用 compose/.env 改动后(会重建容器)
|
||||
docker compose up -d
|
||||
# 只改了 custom/ 里的内容(无 compose 变化)时:
|
||||
# docker compose restart gitea
|
||||
sudo ./scripts/verify.sh # 4. 体检
|
||||
curl -s https://cpp.tongji.sh/QA/ | grep -c 课程答疑平台 # 5. 抽查首页
|
||||
```
|
||||
|
||||
> **⚠️ 权限坑(2026-09 生产真的挂过一次)**:`custom/` 是只读挂载,而容器里的 Gitea 以
|
||||
> `git`(982)运行。编辑器/工具写出来的文件常是 `600`,只读挂载**不会**放宽权限检查,
|
||||
> 启动时直接:
|
||||
> ```text
|
||||
> [F] Gitea can't run with template errors: open home.tmpl: permission denied
|
||||
> ```
|
||||
> 然后 `Restarting` 死循环。**预览环境不会暴露它** —— 预览容器的 uid 就是宿主用户
|
||||
> (`PREVIEW_UID`),同一属主当然读得到。
|
||||
> `build.py` 每次都会把 `custom/` 补齐成「组/其他人可读,目录可进入」,`--check` 也会在
|
||||
> 不可读时报错退出,所以**部署前跑一次 `build.py` 就不会中招**。
|
||||
> 手工体检:`docker compose exec -T -u git gitea head -c1 /data/gitea/templates/home.tmpl`。
|
||||
|
||||
回滚:去掉挂载与环境变量 → `docker compose up -d`;或 `git revert` 本目录改动 →
|
||||
`docker compose restart gitea`。
|
||||
|
||||
### 4.4 升级 Gitea 时的流程
|
||||
|
||||
```bash
|
||||
# 1. 同步版本号: customization/gitea-version.txt 与 deploy/.env 的 GITEA_VERSION
|
||||
# 2. 拉上游快照
|
||||
customization/fetch-upstream.sh 1.28.0
|
||||
# 3. 看上游改了什么,特别是我们整文件覆盖过的模板
|
||||
git diff customization/upstream/
|
||||
# 4. 把上游的结构性改动合并进 custom/templates/**.tmpl
|
||||
# 5. 重新生成语言文件(上游新增的键会自动带进来)
|
||||
python3 customization/build.py
|
||||
# 6. 预览验证
|
||||
customization/preview/preview.sh up && customization/preview/preview.sh check
|
||||
# 7. 备份 + 升级(与 deploy/README.md §7.1 一致)
|
||||
cd deploy && ./scripts/backup.sh --quiesce && docker compose pull gitea && docker compose up -d gitea
|
||||
```
|
||||
|
||||
`build.py` 会在「我们覆盖的键在新版本里不存在」「占位符对不上」时直接失败,
|
||||
把升级风险挡在部署之前。
|
||||
|
||||
---
|
||||
|
||||
## 5. 已验证 / 未覆盖
|
||||
|
||||
已在本机实测(官方 1.27.3 镜像 + 独立预览实例):
|
||||
|
||||
- ✅ 落地页替换为定制 `home.tmpl`(4 张卡片、无 Gitea 功能介绍)
|
||||
- ✅ `[ui.meta]` 元信息替换(`GITEA__ui_0X2E_meta__*` 编码有效)
|
||||
- ✅ 页脚 Powered by / 版本号可关闭
|
||||
- ✅ 导航栏 `docs.gitea.com` 外链替换为官网《提问指南》(`/Website/qa/ask/`)
|
||||
- ✅ 平台内 `public/assets/tjhlp/ask-guide.html` 已删除, 页面与 Issue 模板全部指向官网
|
||||
- ✅ zh-CN 整份覆盖后,仓库 Issue 页显示「创建 Issue / 前往 Issue」,不再出现「工单」
|
||||
- ✅ 语言文件在 dev 模式下改动即生效(模板仍须重启)
|
||||
- ✅ 登录页改成「统一身份认证」优先 + 「管理员登录」卡片,表单仍可正常登录/报错
|
||||
- ✅ 关闭 `ENABLE_PASSKEY_AUTHENTICATION` 后,登录页不再出现空的通行密钥方框
|
||||
- ✅ 首页(登录后)顶部出现学期答疑入口卡片: 只认 `tjhlp-<5 位数字>`、取最新学期、
|
||||
无匹配则不显示(预览里用 3 个用户 × 4 个组织验证过)
|
||||
- ✅ 打开 `[ui] DEFAULT_SHOW_FULL_NAME` 后, Issue 的「由 X 创建」与正文/评论作者
|
||||
显示 `full_name`(姓名), 未填姓名的用户回退显示 login(学号)(预览实测)
|
||||
|
||||
尚未覆盖(需要时按同样套路加):
|
||||
|
||||
- Logo / favicon 换成本课程的图(需要设计稿;放到 `custom/public/assets/img/`)
|
||||
- 注册页(`user/auth/signup.tmpl`)、错误页文案
|
||||
- 更多术语(合并请求 / 仓库 / 里程碑…)—— 在 `overrides/` 里加规则即可
|
||||
- 自定义主题配色(`[ui] THEMES` + `custom/public/assets/css/theme-*.css`)
|
||||
Executable
+210
@@ -0,0 +1,210 @@
|
||||
#!/usr/bin/env python3
|
||||
"""生成 TJHLP 定制用的 Gitea 简体中文语言文件。
|
||||
|
||||
Gitea 只支持「整个文件覆盖」locale: 放在 custom/options/locale/locale_zh-CN.json 的
|
||||
文件会完全替换内置的 zh-CN。缺失的键不会退回中文, 而是退回默认语言(en-US),
|
||||
所以覆盖文件必须是完整的一份, 不能只写改动项。本脚本用来从上游快照
|
||||
(upstream/<版本>/locale_zh-CN.json) + 我们的覆盖(rules / overrides)确定性地产出
|
||||
这份完整文件, 避免手工维护 3900 个键。
|
||||
|
||||
用法:
|
||||
python3 customization/build.py # 生成 custom/options/locale/locale_zh-CN.json
|
||||
python3 customization/build.py --check # 只校验磁盘上的生成物是否最新(CI / 部署前)
|
||||
python3 customization/build.py --quiet # 不打印改动清单
|
||||
|
||||
除了生成语言文件, 本脚本还负责把 custom/ 的权限规范成「容器用户可读」——
|
||||
Gitea 容器以镜像内的 git 用户运行, 而编辑器写出来的文件可能是 600, 只读挂载进容器后
|
||||
会 permission denied 并让 Gitea 拒绝启动(见 deploy/README.md 已知陷阱 3)。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import re
|
||||
import stat
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
HERE = Path(__file__).resolve().parent
|
||||
CUSTOM_DIR = HERE / "custom"
|
||||
OUT_PATH = CUSTOM_DIR / "options" / "locale" / "locale_zh-CN.json"
|
||||
|
||||
# Go 模板/printf 里的格式化占位符, 例如 %s %d %v %[1]s %[2]d %%
|
||||
FORMAT_RE = re.compile(r"%(?:\[(\d+)\])?[-+# 0-9.]*[a-zA-Z%]")
|
||||
|
||||
|
||||
def load_json(path: Path):
|
||||
with path.open(encoding="utf-8") as f:
|
||||
return json.load(f)
|
||||
|
||||
|
||||
def strip_comments(obj: dict) -> dict:
|
||||
"""去掉以 _ 开头的说明键, 它们只是给人看的元数据。"""
|
||||
return {k: v for k, v in obj.items() if not k.startswith("_")}
|
||||
|
||||
|
||||
def format_verbs(text: str) -> list[str]:
|
||||
return FORMAT_RE.findall(text)
|
||||
|
||||
|
||||
def _is_cjk_ideograph(ch: str) -> bool:
|
||||
# 只在汉字旁边补空格; 中文标点(。,、「」…)本身不需要与英文分隔
|
||||
return "\u4e00" <= ch <= "\u9fff"
|
||||
|
||||
|
||||
def _pad_for(edge: str, neighbour: str) -> str:
|
||||
"""中英混排时给替换结果补一个空格: 汉字紧邻英文/数字才需要。"""
|
||||
if edge and edge[0].isascii() and edge[0].isalnum() and neighbour and _is_cjk_ideograph(neighbour):
|
||||
return " "
|
||||
return ""
|
||||
|
||||
|
||||
def apply_rule(text: str, src: str, dst: str) -> str:
|
||||
"""字面替换 src -> dst, 并在中英交界处补空格(工单 -> " Issue ")。"""
|
||||
out: list[str] = []
|
||||
pos = 0
|
||||
while True:
|
||||
found = text.find(src, pos)
|
||||
if found < 0:
|
||||
out.append(text[pos:])
|
||||
return "".join(out)
|
||||
out.append(text[pos:found])
|
||||
left = text[found - 1] if found > 0 else ""
|
||||
right = text[found + len(src)] if found + len(src) < len(text) else ""
|
||||
out.append(_pad_for(dst, left) + dst + _pad_for(dst[::-1], right))
|
||||
pos = found + len(src)
|
||||
|
||||
|
||||
def build() -> tuple[dict, dict, list[tuple[str, str, str]]]:
|
||||
version = (HERE / "gitea-version.txt").read_text(encoding="utf-8").strip()
|
||||
upstream_path = HERE / "upstream" / version / "options" / "locale" / "locale_zh-CN.json"
|
||||
if not upstream_path.exists():
|
||||
sys.exit(f"缺少上游快照: {upstream_path} (先执行 customization/fetch-upstream.sh {version})")
|
||||
|
||||
upstream: dict[str, object] = load_json(upstream_path)
|
||||
locale: dict[str, object] = dict(upstream)
|
||||
rules = strip_comments(load_json(HERE / "overrides" / "locale_zh-CN.rules.json"))["rules"]
|
||||
overrides = strip_comments(load_json(HERE / "overrides" / "locale_zh-CN.json"))["overrides"]
|
||||
|
||||
errors: list[str] = []
|
||||
|
||||
for rule in rules:
|
||||
src, dst = rule["from"], rule["to"]
|
||||
for key, value in locale.items():
|
||||
if isinstance(value, str) and src in value:
|
||||
locale[key] = apply_rule(value, src, dst)
|
||||
|
||||
for key, new_value in overrides.items():
|
||||
if key not in upstream:
|
||||
errors.append(f"覆盖键不存在于上游: {key}")
|
||||
continue
|
||||
old_value = upstream[key]
|
||||
if not isinstance(old_value, str):
|
||||
errors.append(f"覆盖键在上游不是字符串: {key}")
|
||||
continue
|
||||
if format_verbs(old_value) != format_verbs(new_value):
|
||||
errors.append(f"占位符不一致: {key}\n 上游: {old_value}\n 覆盖: {new_value}")
|
||||
locale[key] = new_value
|
||||
|
||||
if errors:
|
||||
sys.exit("构建失败:\n - " + "\n - ".join(errors))
|
||||
|
||||
changes = [(k, str(upstream[k]), str(v)) for k, v in locale.items() if upstream.get(k) != v]
|
||||
return locale, upstream, changes
|
||||
|
||||
|
||||
def render(locale: dict) -> str:
|
||||
# 保持上游的键顺序, 让 git diff 只显示真正改动的行
|
||||
return json.dumps(locale, ensure_ascii=False, indent=2) + "\n"
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# custom/ 的权限
|
||||
# ---------------------------------------------------------------------------
|
||||
# Gitea 容器以镜像内的 git 用户运行(部署里 USER_UID=982), 而编辑器/工具写出来的文件
|
||||
# 可能是 600(仅属主可读)。custom/ 是只读挂载进容器的, 一旦容器用户读不到,
|
||||
# prod 模式会直接拒绝启动: "Gitea can't run with template errors: open home.tmpl:
|
||||
# permission denied"(2026-09 生产真的这样挂过一次)。预览之所以没暴露, 是因为
|
||||
# 预览容器的 uid 就是宿主用户。
|
||||
# 所以每次生成都顺手把 custom/ 规范成「组 + 其他人可读, 目录可进入」。
|
||||
def unreadable_paths(root: Path) -> list[Path]:
|
||||
"""列出容器用户(非属主)读不到的文件/进不去的目录。"""
|
||||
bad: list[Path] = []
|
||||
for path in sorted(root.rglob("*")):
|
||||
mode = path.stat().st_mode
|
||||
need = stat.S_IROTH | (stat.S_IXOTH if path.is_dir() else 0)
|
||||
if mode & need != need:
|
||||
bad.append(path)
|
||||
return bad
|
||||
|
||||
|
||||
def ensure_readable(root: Path) -> list[Path]:
|
||||
"""补齐 g+r / o+r(目录再补 o+x), 返回被修正的路径。"""
|
||||
fixed: list[Path] = []
|
||||
for path in sorted(root.rglob("*")):
|
||||
mode = path.stat().st_mode
|
||||
want = mode | stat.S_IRGRP | stat.S_IROTH
|
||||
if path.is_dir():
|
||||
want |= stat.S_IXGRP | stat.S_IXOTH
|
||||
if want != mode:
|
||||
path.chmod(want)
|
||||
fixed.append(path)
|
||||
return fixed
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument("--check", action="store_true", help="只校验, 不写入")
|
||||
parser.add_argument("--quiet", action="store_true", help="不打印改动清单")
|
||||
args = parser.parse_args()
|
||||
|
||||
locale, upstream, changes = build()
|
||||
rendered = render(locale)
|
||||
|
||||
if not args.quiet:
|
||||
print(f"上游键数: {len(upstream)} 覆盖后键数: {len(locale)} 改动: {len(changes)} 处")
|
||||
for key, old, new in changes:
|
||||
print(f" {key}\n - {old}\n + {new}")
|
||||
|
||||
if args.check:
|
||||
current = OUT_PATH.read_text(encoding="utf-8") if OUT_PATH.exists() else ""
|
||||
if current != rendered:
|
||||
print(f"✗ {OUT_PATH} 与覆盖配置不一致, 请运行 python3 customization/build.py", file=sys.stderr)
|
||||
return 1
|
||||
print(f"✓ {OUT_PATH} 是最新的")
|
||||
|
||||
bad = unreadable_paths(CUSTOM_DIR)
|
||||
if bad:
|
||||
print(
|
||||
"✗ 下列文件/目录对容器用户不可读(挂载进容器会 permission denied), "
|
||||
"请运行 python3 customization/build.py 修正:",
|
||||
file=sys.stderr,
|
||||
)
|
||||
for path in bad:
|
||||
print(f" {path.relative_to(HERE)} {oct(path.stat().st_mode & 0o777)}", file=sys.stderr)
|
||||
return 1
|
||||
print("✓ custom/ 权限正常(容器用户可读)")
|
||||
return 0
|
||||
|
||||
OUT_PATH.parent.mkdir(parents=True, exist_ok=True)
|
||||
try:
|
||||
OUT_PATH.write_text(rendered, encoding="utf-8")
|
||||
except PermissionError as exc:
|
||||
raise SystemExit(
|
||||
f"写入失败: {exc}\n"
|
||||
f" 多半是 docker 以 root 创建过这个挂载源目录(bind mount 的源目录不存在时它会这么做),\n"
|
||||
f" 普通用户就写不进去了。删掉再重试: sudo rm -rf {OUT_PATH.parent}\n"
|
||||
f" (仓库里 customization/custom/options/.gitkeep 就是为防止这种情况而存在的)"
|
||||
) from exc
|
||||
print(f"✓ 已生成 {OUT_PATH}")
|
||||
fixed = ensure_readable(CUSTOM_DIR)
|
||||
if fixed:
|
||||
print(f"✓ 修正了 {len(fixed)} 个权限过紧的路径(容器用户需要可读):")
|
||||
for path in fixed:
|
||||
print(f" {path.relative_to(HERE)}")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Executable
+131
@@ -0,0 +1,131 @@
|
||||
#!/usr/bin/env bash
|
||||
# 定制生效断言 —— 对任意实例跑一遍, 预览与生产共用。
|
||||
# 用法:
|
||||
# customization/check.sh http://127.0.0.1:2081 # 预览
|
||||
# customization/check.sh https://cpp.tongji.sh/QA # 生产(CI 里也调这个)
|
||||
#
|
||||
# 退出码: 0 全通过 / 1 有断言失败 / 2 用法错误。
|
||||
# 只读: 只发 GET, 不改任何东西。
|
||||
set -uo pipefail
|
||||
|
||||
BASE_URL="${1:-}"
|
||||
if [[ -z ${BASE_URL} ]]; then
|
||||
sed -n '2,9p' "$0"
|
||||
exit 2
|
||||
fi
|
||||
BASE_URL="${BASE_URL%/}"
|
||||
ORIGIN="$(printf '%s' "${BASE_URL}" | sed -E 's#(^https?://[^/]+).*#\1#')"
|
||||
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
|
||||
fail=0
|
||||
ok() { printf ' ✓ %s\n' "$1"; }
|
||||
bad() {
|
||||
printf ' ✗ %s\n' "$1"
|
||||
fail=1
|
||||
}
|
||||
skip() { printf ' – %s\n' "$1"; }
|
||||
|
||||
tmp="$(mktemp -d)"
|
||||
trap 'rm -rf "${tmp}"' EXIT
|
||||
# --noproxy: 验证目标都在内网, 走代理只会把 200 变成 502(见 deploy/README.md 陷阱 5)
|
||||
curl_() { curl -sS --noproxy '*' --max-time 20 "$@"; }
|
||||
|
||||
echo "== 定制检查 ${BASE_URL} =="
|
||||
|
||||
# --- 首页 -------------------------------------------------------------------
|
||||
if ! curl_ -fsS -H 'Accept-Language: zh-CN' "${BASE_URL}/" -o "${tmp}/home.html"; then
|
||||
echo " ✗ 首页打不开(HTTP 非 2xx), 后面不再检查"
|
||||
exit 1
|
||||
fi
|
||||
ok "首页可访问"
|
||||
|
||||
grep -q "先搜索,再提问" "${tmp}/home.html" &&
|
||||
ok "首页用的是定制模板 home.tmpl" || bad "首页没有定制模板的内容"
|
||||
grep -q "https://cpp.tongji.sh/Website/qa/ask/" "${tmp}/home.html" &&
|
||||
ok "导航栏/首页已指向官网提问指南(/Website/qa/ask/)" ||
|
||||
bad "没找到官网提问指南链接(页面还是旧模板? 模板改动要重启 gitea 才生效)"
|
||||
! grep -q "painless\|极易搭建\|Easy to install\|Cross-platform" "${tmp}/home.html" &&
|
||||
ok "首页已无 Gitea 功能介绍" || bad "首页仍有 Gitea 功能介绍文案"
|
||||
! grep -qi "powered by" "${tmp}/home.html" &&
|
||||
ok "页脚已无 Powered by Gitea" || bad "页脚仍有 Powered by"
|
||||
! grep -q "docs.gitea.com" "${tmp}/home.html" &&
|
||||
ok "页面已无 docs.gitea.com 外链" || bad "仍有 docs.gitea.com 外链"
|
||||
grep -q 'name="description" content="同济大学高级语言程序设计课程答疑平台"' "${tmp}/home.html" &&
|
||||
ok "meta description 已替换" || bad "meta description 未替换"
|
||||
|
||||
# --- 与课程官网的联动 -------------------------------------------------------
|
||||
grep -q "https://cpp.tongji.sh/Website/" "${tmp}/home.html" &&
|
||||
ok "首页/导航栏已链接课程官网" || bad "首页没有课程官网链接"
|
||||
grep -q "https://cpp.tongji.sh/Website/qa/ask/" "${tmp}/home.html" &&
|
||||
ok "首页已链接官网提问指南" || bad "首页没有官网提问指南链接"
|
||||
! grep -q "Website/ask-question/\|Website/faq/\|Website/contact\"" "${tmp}/home.html" &&
|
||||
ok "没有指向官网已迁移/失效的旧地址" ||
|
||||
bad "仍有旧地址(ask-question / faq / contact 无 .html)"
|
||||
# 站内提问指南页已按决定删除: 提问指南只在官网保留一份
|
||||
if curl_ -fsS -o /dev/null "${BASE_URL}/assets/tjhlp/ask-guide.html" 2>/dev/null; then
|
||||
bad "平台内还留着 ask-guide.html(提问指南应只在官网)"
|
||||
else
|
||||
ok "平台内提问指南页已删除"
|
||||
fi
|
||||
|
||||
# --- 中文术语与登录页 -------------------------------------------------------
|
||||
if curl_ -fsS -H 'Accept-Language: zh-CN' "${BASE_URL}/user/login" -o "${tmp}/login.html"; then
|
||||
ok "登录页可访问"
|
||||
grep -q "管理员登录" "${tmp}/login.html" &&
|
||||
ok "登录页有独立的「管理员登录」卡片" || bad "登录页缺少管理员登录卡片"
|
||||
! grep -q "webauthn-error\|signin-passkey" "${tmp}/login.html" &&
|
||||
ok "登录页已无空的通行密钥(WebAuthn)方框" || bad "登录页仍有通行密钥区块"
|
||||
# OIDC 入口: 配了认证源的实例才会渲染 external-login-navigator
|
||||
if grep -q 'id="external-login-navigator"' "${tmp}/login.html"; then
|
||||
href="$(grep -o 'href="[^"]*/user/oauth2/[^"]*"' "${tmp}/login.html" | head -1 |
|
||||
sed -E 's/^href="//; s/"$//')"
|
||||
if [[ -z ${href} ]]; then
|
||||
bad "登录页有认证源区块但没解析出 OAuth2 链接"
|
||||
else
|
||||
code="$(curl_ -o /dev/null -w '%{http_code}' "${ORIGIN}${href}")"
|
||||
# 307 = 认证源注册成功并跳转统一身份认证; 404 = 认证源没注册上(见 README 陷阱 6)
|
||||
[[ ${code} == 307 ]] &&
|
||||
ok "OIDC 入口 ${href} 返回 307(跳转统一身份认证)" ||
|
||||
bad "OIDC 入口返回 ${code}, 期望 307(404 = 认证源没注册上)"
|
||||
fi
|
||||
else
|
||||
skip "该实例未配置认证源, 跳过 OIDC 入口检查(预览实例属此情况)"
|
||||
fi
|
||||
else
|
||||
bad "登录页打不开"
|
||||
fi
|
||||
|
||||
# 术语: 中文界面里不该再出现「工单」
|
||||
if curl_ -fsS -H 'Accept-Language: zh-CN' -o "${tmp}/issues.html" \
|
||||
"${BASE_URL}/course-team/tjhlp-gitea/issues"; then
|
||||
! grep -q "工单" "${tmp}/issues.html" &&
|
||||
ok "Issue 列表页中文界面已无「工单」" || bad "Issue 列表页仍有「工单」"
|
||||
else
|
||||
skip "读不到 issue 列表页(需要登录?), 跳过「工单」检查"
|
||||
fi
|
||||
|
||||
# --- 仓库内文件(在 checkout 里跑时才有意义) --------------------------------
|
||||
if [[ -d ${ROOT}/issue-templates ]]; then
|
||||
! grep -rq "example.com" "${ROOT}/issue-templates/" &&
|
||||
ok "Issue 模板已无 example.com 占位链接" || bad "Issue 模板里仍有 example.com"
|
||||
fi
|
||||
if [[ -f ${ROOT}/customization/custom/options/locale/locale_zh-CN.json ]]; then
|
||||
! grep -q "工单" "${ROOT}/customization/custom/options/locale/locale_zh-CN.json" &&
|
||||
ok "生成的 zh-CN 语言文件已无「工单」" || bad "语言文件里仍有「工单」"
|
||||
fi
|
||||
# 首页(登录后)的学期答疑入口卡片: 渲染结果需要登录才能看, 这里只断言模板层
|
||||
# (运行时的渲染断言在 customization/preview/preview.sh check 里, 要登录)。
|
||||
if [[ -f ${ROOT}/customization/custom/templates/custom/tjhlp_semester_card.tmpl ]]; then
|
||||
grep -q "本学期答疑入口" "${ROOT}/customization/custom/templates/custom/tjhlp_semester_card.tmpl" &&
|
||||
ok "首页答疑入口卡片模板在位" || bad "卡片模板里没有预期的内容"
|
||||
grep -q 'template "custom/tjhlp_semester_card"' \
|
||||
"${ROOT}/customization/custom/templates/user/dashboard/dashboard.tmpl" &&
|
||||
ok "dashboard.tmpl 已 include 学期答疑入口卡片" || bad "dashboard.tmpl 没有 include 卡片"
|
||||
fi
|
||||
|
||||
if [[ ${fail} == 0 ]]; then
|
||||
echo "全部检查通过"
|
||||
else
|
||||
echo "存在检查未通过项"
|
||||
fi
|
||||
exit "${fail}"
|
||||
@@ -0,0 +1,15 @@
|
||||
# 这个文件唯一的用途: 让 git 跟踪住这个空目录。
|
||||
#
|
||||
# customization/custom/ 下的三个子目录会被逐个 bind mount 进容器:
|
||||
# custom/options -> /data/gitea/options
|
||||
# custom/public -> /data/gitea/public
|
||||
# custom/templates-> /data/gitea/templates
|
||||
# 如果 options/ 在全新克隆里不存在(它下面只放生成出来的 locale_zh-CN.json, 而那个文件
|
||||
# 是 gitignore 的), 那么 docker compose 会【以 root 创建】这个挂载源目录 —— 之后
|
||||
# 普通用户跑 customization/build.py 就写不进去:
|
||||
# PermissionError: [Errno 13] Permission denied: .../custom/options/locale
|
||||
# 于是语言文件永远生成不出来, 中文界面退回上游文案(「工单」又回来了)。
|
||||
# 2026-09-13 第一次把生产切到部署克隆时真实踩到。
|
||||
#
|
||||
# 有了这个占位文件, 目录随 checkout 就存在且属于当前用户, 问题从结构上消失。
|
||||
# 真正有内容的是 custom/templates 与 custom/public, 它们不需要占位。
|
||||
@@ -0,0 +1,15 @@
|
||||
# 这个文件唯一的用途: 让 git 跟踪住这个(现在)空的目录。
|
||||
#
|
||||
# customization/custom/ 下的三个子目录会被逐个 bind mount 进容器:
|
||||
# custom/options -> /data/gitea/options
|
||||
# custom/public -> /data/gitea/public
|
||||
# custom/templates-> /data/gitea/templates
|
||||
#
|
||||
# public/ 原来放的是站内「提问指南」静态页
|
||||
# (public/assets/tjhlp/ask-guide.html)。2026-09 起提问指南只在课程官网保留一份
|
||||
# (https://cpp.tongji.sh/Website/qa/ask/), 平台内的副本已删除, 这个目录就空了。
|
||||
# 目录不能跟着消失: bind mount 的源目录不存在时 docker compose 会【以 root 创建】它,
|
||||
# 之后普通用户/CI 都用不了(同样的坑见 options/.gitkeep)。
|
||||
#
|
||||
# 将来要往平台里放静态资源时, 直接加在 public/ 下即可(例如
|
||||
# public/assets/img/logo.svg -> /QA/assets/img/logo.svg)。
|
||||
@@ -0,0 +1,193 @@
|
||||
{{/*
|
||||
导航栏, 整文件覆盖 Gitea 内置 templates/base/head_navbar.tmpl。
|
||||
相对上游只改了两处: 未登录时的「帮助」和用户菜单里的「帮助」指向课程提问指南,
|
||||
不再外链 docs.gitea.com。上游基线见 upstream/<版本>/templates/base/head_navbar.tmpl,
|
||||
升级时请 diff 该基线后重新合并, 不要直接覆盖本文件。
|
||||
*/}}
|
||||
<nav id="navbar" aria-label="{{ctx.Locale.Tr "aria.navbar"}}">
|
||||
<div class="navbar-left">
|
||||
<!-- the logo -->
|
||||
<a class="item" id="navbar-logo" href="{{AppSubUrl}}/" aria-label="{{if .IsSigned}}{{ctx.Locale.Tr "dashboard"}}{{else}}{{ctx.Locale.Tr "home_title"}}{{end}}">
|
||||
<img width="30" height="30" src="{{AssetUrlPrefix}}/img/logo.svg" alt="{{ctx.Locale.Tr "logo"}}" aria-hidden="true">
|
||||
</a>
|
||||
|
||||
<!-- mobile right menu, it must be here because in mobile view, each item is a flex column, the first item is a full row column -->
|
||||
<div class="ui secondary menu navbar-mobile-right only-mobile">
|
||||
{{template "base/head_navbar_icons" dict "PageGlobalData" .PageGlobalData}}
|
||||
<button class="item ui icon mini button tw-m-0" id="navbar-expand-toggle" aria-label="{{ctx.Locale.Tr "home.nav_menu"}}">{{svg "octicon-three-bars"}}</button>
|
||||
</div>
|
||||
|
||||
<!-- navbar links non-mobile -->
|
||||
{{if and .IsSigned .MustChangePassword}}
|
||||
{{/* No links */}}
|
||||
{{else if .IsSigned}}
|
||||
{{if not ctx.Consts.RepoUnitTypeIssues.UnitGlobalDisabled}}
|
||||
<a class="item{{if .PageIsIssues}} active{{end}}" href="{{AppSubUrl}}/issues">{{ctx.Locale.Tr "issues"}}</a>
|
||||
{{end}}
|
||||
{{if not ctx.Consts.RepoUnitTypePullRequests.UnitGlobalDisabled}}
|
||||
<a class="item{{if .PageIsPulls}} active{{end}}" href="{{AppSubUrl}}/pulls">{{ctx.Locale.Tr "pull_requests"}}</a>
|
||||
{{end}}
|
||||
{{if not (and ctx.Consts.RepoUnitTypeIssues.UnitGlobalDisabled ctx.Consts.RepoUnitTypePullRequests.UnitGlobalDisabled)}}
|
||||
{{if .ShowMilestonesDashboardPage}}
|
||||
<a class="item{{if .PageIsMilestonesDashboard}} active{{end}}" href="{{AppSubUrl}}/milestones">{{ctx.Locale.Tr "milestones"}}</a>
|
||||
{{end}}
|
||||
{{end}}
|
||||
<a class="item{{if .PageIsExplore}} active{{end}}" href="{{AppSubUrl}}/explore/repos">{{ctx.Locale.Tr "explore_title"}}</a>
|
||||
{{else if .IsLandingPageOrganizations}}
|
||||
<a class="item{{if .PageIsExplore}} active{{end}}" href="{{AppSubUrl}}/explore/organizations">{{ctx.Locale.Tr "explore_title"}}</a>
|
||||
{{else}}
|
||||
<a class="item{{if .PageIsExplore}} active{{end}}" href="{{AppSubUrl}}/explore/repos">{{ctx.Locale.Tr "explore_title"}}</a>
|
||||
{{end}}
|
||||
|
||||
{{template "custom/extra_links" .}}
|
||||
|
||||
{{if not .IsSigned}}
|
||||
<a class="item" href="https://cpp.tongji.sh/Website/">课程官网</a>
|
||||
<a class="item" href="https://cpp.tongji.sh/Website/qa/ask/">提问指南</a>
|
||||
{{end}}
|
||||
</div>
|
||||
|
||||
<!-- the full dropdown menus -->
|
||||
<div class="navbar-right">
|
||||
{{if and .IsSigned .MustChangePassword}}
|
||||
<div class="ui dropdown jump item" data-tooltip-content="{{ctx.Locale.Tr "user_profile_and_more"}}">
|
||||
<span class="text">
|
||||
{{ctx.AvatarUtils.Avatar .SignedUser 24 "tw-mr-1"}}
|
||||
<span class="only-mobile">{{.SignedUser.Name}}</span>
|
||||
<span class="not-mobile flex-text-block">{{svg "octicon-triangle-down"}}</span>
|
||||
</span>
|
||||
<div class="menu user-menu">
|
||||
<div class="header">
|
||||
{{ctx.Locale.Tr "signed_in_as"}} <strong>{{.SignedUser.Name}}</strong>
|
||||
</div>
|
||||
|
||||
<div class="divider"></div>
|
||||
<a class="item" href="{{AppSubUrl}}/user/logout">
|
||||
{{svg "octicon-sign-out"}}
|
||||
{{ctx.Locale.Tr "sign_out"}}
|
||||
</a>
|
||||
</div><!-- end content avatar menu -->
|
||||
</div><!-- end dropdown avatar menu -->
|
||||
{{else if .IsSigned}}
|
||||
{{template "base/head_navbar_icons" dict "ItemExtraClass" "not-mobile" "PageGlobalData" .PageGlobalData}}
|
||||
<div class="ui dropdown jump item" data-tooltip-content="{{ctx.Locale.Tr "create_new"}}">
|
||||
<span class="flex-text-block">
|
||||
{{svg "octicon-plus"}}
|
||||
<span class="not-mobile flex-text-block">{{svg "octicon-triangle-down"}}</span>
|
||||
<span class="only-mobile">{{ctx.Locale.Tr "create_new"}}</span>
|
||||
</span>
|
||||
<div class="menu">
|
||||
<a class="item" href="{{AppSubUrl}}/repo/create">
|
||||
{{svg "octicon-plus"}} {{ctx.Locale.Tr "new_repo"}}
|
||||
</a>
|
||||
{{if not .DisableMigrations}}
|
||||
<a class="item" href="{{AppSubUrl}}/repo/migrate">
|
||||
{{svg "octicon-repo-push"}} {{ctx.Locale.Tr "new_migrate"}}
|
||||
</a>
|
||||
{{end}}
|
||||
{{if .SignedUser.CanCreateOrganization}}
|
||||
<a class="item" href="{{AppSubUrl}}/org/create">
|
||||
{{svg "octicon-organization"}} {{ctx.Locale.Tr "new_org"}}
|
||||
</a>
|
||||
{{end}}
|
||||
</div><!-- end content create new menu -->
|
||||
</div><!-- end dropdown menu create new -->
|
||||
|
||||
<div class="ui dropdown jump item" data-tooltip-content="{{ctx.Locale.Tr "user_profile_and_more"}}">
|
||||
<span class="text tw-flex tw-items-center">
|
||||
<span class="navbar-avatar">
|
||||
{{ctx.AvatarUtils.Avatar .SignedUser 24 "tw-mr-2"}}
|
||||
{{if .IsAdmin}}{{svg "octicon-shield-check" 16 "navbar-admin-badge"}}{{end}}
|
||||
</span>
|
||||
<span class="only-mobile">{{.SignedUser.Name}}</span>
|
||||
<span class="not-mobile flex-text-block">{{svg "octicon-triangle-down"}}</span>
|
||||
</span>
|
||||
<div class="menu user-menu">
|
||||
<div class="header">
|
||||
{{ctx.Locale.Tr "signed_in_as"}} <strong>{{.SignedUser.Name}}</strong>
|
||||
</div>
|
||||
|
||||
<div class="divider"></div>
|
||||
<a class="item" href="{{.SignedUser.HomeLink}}">
|
||||
{{svg "octicon-person"}}
|
||||
{{ctx.Locale.Tr "your_profile"}}
|
||||
</a>
|
||||
{{if not .DisableStars}}
|
||||
<a class="item" href="{{.SignedUser.HomeLink}}?tab=stars">
|
||||
{{svg "octicon-star"}}
|
||||
{{ctx.Locale.Tr "your_starred"}}
|
||||
</a>
|
||||
{{end}}
|
||||
<a class="item" href="{{AppSubUrl}}/notifications/subscriptions">
|
||||
{{svg "octicon-bell"}}
|
||||
{{ctx.Locale.Tr "notification.subscriptions"}}
|
||||
</a>
|
||||
<a class="{{if .PageIsUserSettings}}active {{end}}item" href="{{AppSubUrl}}/user/settings">
|
||||
{{svg "octicon-tools"}}
|
||||
{{ctx.Locale.Tr "your_settings"}}
|
||||
</a>
|
||||
<a class="item" href="https://cpp.tongji.sh/Website/qa/ask/">
|
||||
{{svg "octicon-question"}}
|
||||
提问指南
|
||||
</a>
|
||||
<a class="item" href="https://cpp.tongji.sh/Website/">
|
||||
{{svg "octicon-book"}}
|
||||
课程官网
|
||||
</a>
|
||||
{{if .IsAdmin}}
|
||||
<div class="divider"></div>
|
||||
<a class="{{if .PageIsAdmin}}active {{end}}item" href="{{AppSubUrl}}/-/admin">
|
||||
{{svg "octicon-server"}}
|
||||
{{ctx.Locale.Tr "admin_panel"}}
|
||||
</a>
|
||||
{{end}}
|
||||
<div class="divider"></div>
|
||||
<a class="item" href="{{AppSubUrl}}/user/logout">
|
||||
{{svg "octicon-sign-out"}}
|
||||
{{ctx.Locale.Tr "sign_out"}}
|
||||
</a>
|
||||
</div><!-- end content avatar menu -->
|
||||
</div><!-- end dropdown avatar menu -->
|
||||
{{else}}
|
||||
{{if .ShowRegistrationButton}}
|
||||
<a class="item{{if .PageIsSignUp}} active{{end}}" href="{{AppSubUrl}}/user/sign_up">
|
||||
{{svg "octicon-person"}}
|
||||
<span class="tw-ml-1">{{ctx.Locale.Tr "register"}}</span>
|
||||
</a>
|
||||
{{end}}
|
||||
<a class="item{{if .PageIsSignIn}} active{{end}}" rel="nofollow" href="{{AppSubUrl}}/user/login">
|
||||
{{svg "octicon-sign-in"}}
|
||||
<span class="tw-ml-1">{{ctx.Locale.Tr "sign_in"}}</span>
|
||||
</a>
|
||||
{{end}}
|
||||
</div><!-- end full right menu -->
|
||||
|
||||
{{$activeStopwatch := and .PageGlobalData (call .PageGlobalData.GetActiveStopwatch)}}
|
||||
{{if $activeStopwatch}}
|
||||
<div class="active-stopwatch-popup tippy-target">
|
||||
<div class="flex-text-block tw-p-3">
|
||||
<a class="stopwatch-link flex-text-block muted" href="{{$activeStopwatch.IssueLink}}">
|
||||
{{svg "octicon-issue-opened" 16}}
|
||||
<span class="stopwatch-issue">{{$activeStopwatch.RepoSlug}}#{{$activeStopwatch.IssueIndex}}</span>
|
||||
</a>
|
||||
<div class="tw-flex tw-gap-1">
|
||||
<form class="stopwatch-commit form-fetch-action" method="post" action="{{$activeStopwatch.IssueLink}}/times/stopwatch/stop">
|
||||
<button
|
||||
type="submit"
|
||||
class="ui button mini compact basic icon tw-mr-0"
|
||||
data-tooltip-content="{{ctx.Locale.Tr "repo.issues.stop_tracking"}}"
|
||||
>{{svg "octicon-square-fill"}}</button>
|
||||
</form>
|
||||
<form class="stopwatch-cancel form-fetch-action" method="post" action="{{$activeStopwatch.IssueLink}}/times/stopwatch/cancel">
|
||||
<button
|
||||
type="submit"
|
||||
class="ui button mini compact basic icon tw-mr-0"
|
||||
data-tooltip-content="{{ctx.Locale.Tr "repo.issues.cancel_tracking"}}"
|
||||
>{{svg "octicon-trash"}}</button>
|
||||
</form>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
{{end}}
|
||||
</nav>
|
||||
{{template "base/head_banner"}}
|
||||
@@ -0,0 +1,56 @@
|
||||
{{/*
|
||||
首页(登录后的仪表盘)顶部的「本学期答疑入口」大卡片。
|
||||
这是本课程自己的模板, 不是上游文件; 插入点见
|
||||
custom/templates/user/dashboard/dashboard.tmpl(只比上游多一行 include)。
|
||||
|
||||
逻辑:
|
||||
* .Orgs = 当前用户所属的全部组织, 由 routers/web/user/home.go 的 Dashboard
|
||||
处理器注入(organization.GetUserOrgsList, 按 lower_name 升序);
|
||||
* 「学期组织」的判定 = 名字形如 tjhlp-<5 位数字>, 例如
|
||||
tjhlp-26271 = 2026-2027 学年第一学期(26|27|1)
|
||||
旧命名 tjhlp-2026s 这种带字母的不算, 也不认其它前缀的组织;
|
||||
* 取其中名字最大(即最新学期)的一个;
|
||||
* 渲染成一张约 1/3 屏高的大卡片, 按钮直达该组织的 general 仓库 Issue 区。
|
||||
|
||||
匹配不上就整张卡片不显示: 宁可什么都不显示, 也不要给同学一个错的入口。
|
||||
改判定规则/文案只需要动这个文件(不要动 dashboard.tmpl 的其余部分)。
|
||||
*/}}
|
||||
{{$semester := ""}}
|
||||
{{range .Orgs}}
|
||||
{{$name := .Name}}
|
||||
{{$code := StringUtils.TrimPrefix $name "tjhlp-"}}
|
||||
{{if and
|
||||
(ne $code $name)
|
||||
(eq (len $code) 5)
|
||||
(StringUtils.Contains "0123456789" (slice $code 0 1))
|
||||
(StringUtils.Contains "0123456789" (slice $code 1 2))
|
||||
(StringUtils.Contains "0123456789" (slice $code 2 3))
|
||||
(StringUtils.Contains "0123456789" (slice $code 3 4))
|
||||
(StringUtils.Contains "0123456789" (slice $code 4 5))}}
|
||||
{{if or (eq $semester "") (gt $name $semester)}}{{$semester = $name}}{{end}}
|
||||
{{end}}
|
||||
{{end}}
|
||||
{{if $semester}}
|
||||
{{$code := StringUtils.TrimPrefix $semester "tjhlp-"}}
|
||||
{{$term := slice $code 4 5}}
|
||||
{{$termText := printf "第%s学期" $term}}
|
||||
{{if eq $term "1"}}{{$termText = "第一学期"}}{{else if eq $term "2"}}{{$termText = "第二学期"}}{{end}}
|
||||
{{$label := printf "20%s-20%s 学年%s" (slice $code 0 2) (slice $code 2 4) $termText}}
|
||||
<div class="ui container tw-mb-4">
|
||||
{{/* 33vh ≈ 屏幕纵向的 1/3; 用行内样式, 不依赖 Tailwind 是否收录了某个工具类 */}}
|
||||
<div class="ui segment" style="min-height:33vh;display:flex;flex-direction:column;justify-content:center;align-items:center;text-align:center;gap:1rem;padding:1.5rem 1rem">
|
||||
<h2 style="margin:0">本学期答疑入口</h2>
|
||||
<p style="margin:0;color:var(--color-text-light-2)">
|
||||
课程问题请进入下面的答疑区提问(一条 Issue 一个问题), 助教与老师会在那里回复。
|
||||
</p>
|
||||
<a class="ui primary fluid button" style="font-size:1.35rem;padding:1rem;max-width:34rem"
|
||||
href="{{AppSubUrl}}/{{$semester}}/general/issues">
|
||||
进入{{$label}}答疑区
|
||||
</a>
|
||||
<p style="margin:0;color:var(--color-text-light-2)">
|
||||
第一次提问? 先看课程官网的<a href="https://cpp.tongji.sh/Website/qa/ask/">提问指南</a>
|
||||
</p>
|
||||
<p style="margin:0;color:var(--color-text-light-3);font-size:.85rem">学期组织: {{$semester}}</p>
|
||||
</div>
|
||||
</div>
|
||||
{{end}}
|
||||
@@ -0,0 +1,83 @@
|
||||
{{/*
|
||||
首页落地页, 整文件覆盖 Gitea 内置 templates/home.tmpl。
|
||||
|
||||
维护约定:
|
||||
* 上游基线: customization/upstream/<版本>/templates/home.tmpl
|
||||
升级 Gitea 时先 diff 基线, 把上游的结构性改动合并回来, 再重做文案。
|
||||
* 文案直接写中文(平台只面向中文用户), 不复用 Gitea 的 startpage.* 文案,
|
||||
这样首页不再出现「一款极易搭建的自托管 Git 服务」之类的自我推销。
|
||||
* 只改文案/图标/链接, 保留原有 class 与结构, 避免升级后样式失效。
|
||||
* 课程官网地址 https://cpp.tongji.sh/Website/ 出现在本文件、base/head_navbar.tmpl、
|
||||
custom/tjhlp_semester_card.tmpl 以及 issue-templates 下两个 config.yaml 里,
|
||||
换域名/路径时这几处要一起改(见 customization/README.md「与官网联动」)。
|
||||
提问指南只在官网存一份: /Website/qa/ask/ —— 平台内不再保留副本(2026-09 起)。
|
||||
*/}}
|
||||
{{template "base/head" .}}
|
||||
<div role="main" aria-label="{{if .IsSigned}}{{ctx.Locale.Tr "dashboard"}}{{else}}{{ctx.Locale.Tr "home_title"}}{{end}}" class="page-content home">
|
||||
<div class="tw-mb-8 tw-px-8">
|
||||
<div class="center">
|
||||
<img class="logo" width="220" height="220" src="{{AssetUrlPrefix}}/img/logo.svg" alt="{{AppName}}">
|
||||
<div class="hero">
|
||||
<h1 class="ui icon header title tw-text-balance">
|
||||
{{AppName}}
|
||||
</h1>
|
||||
<h2 class="tw-text-balance">同济大学高级语言程序设计课程答疑平台</h2>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="ui stackable middle very relaxed page grid">
|
||||
<div class="eight wide center column">
|
||||
<h1 class="hero ui icon header">
|
||||
{{svg "octicon-search"}} 先搜索,再提问
|
||||
</h1>
|
||||
<p class="large tw-text-balance">
|
||||
大部分问题同学已经问过。提问前请先在
|
||||
<a href="{{AppSubUrl}}/explore/repos">课程答疑仓库</a>
|
||||
的 Issue 列表里搜索关键词,避免重复提问。
|
||||
</p>
|
||||
</div>
|
||||
<div class="eight wide center column">
|
||||
<h1 class="hero ui icon header">
|
||||
{{svg "octicon-checklist"}} 按模板提问
|
||||
</h1>
|
||||
<p class="large tw-text-balance">
|
||||
新建 Issue 时请选择合适的模板,写清题号、相关代码、报错信息和已经尝试过的做法。
|
||||
提问规范与具体做法见课程官网的
|
||||
<a href="https://cpp.tongji.sh/Website/qa/ask/">《提问指南》</a>。
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="ui stackable middle very relaxed page grid">
|
||||
<div class="eight wide center column">
|
||||
<h1 class="hero ui icon header">
|
||||
{{svg "octicon-repo"}} 浏览课程仓库
|
||||
</h1>
|
||||
<p class="large tw-text-balance">
|
||||
一般性问题放在 <code>general</code> 仓库,各次作业的问题放在对应的 <code>hwNN</code> 仓库,
|
||||
可在<a href="{{AppSubUrl}}/explore/repos">仓库列表</a>中查看。
|
||||
</p>
|
||||
</div>
|
||||
<div class="eight wide center column">
|
||||
<h1 class="hero ui icon header">
|
||||
{{svg "octicon-comment-discussion"}} 助教在线答疑
|
||||
</h1>
|
||||
<p class="large tw-text-balance">
|
||||
助教会通过 Issue 回复,并用标签标记重复、已解决、待补充信息等问题。
|
||||
问题解决后请回复确认,便于我们归档。
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="ui center aligned basic segment tw-px-8">
|
||||
<p class="large">
|
||||
相关站点:
|
||||
<a href="https://cpp.tongji.sh/Website/">课程官网</a> ·
|
||||
<a href="https://cpp.tongji.sh/Website/qa/ask/">提问指南</a> ·
|
||||
<a href="https://cpp.tongji.sh/Website/qa/faq/">常见问题</a> ·
|
||||
<a href="https://cpp.tongji.sh/Website/contact.html">联系我们</a>
|
||||
</p>
|
||||
<p>
|
||||
<small>本平台只用于课程答疑,课程通知、作业要求等以课程官网与课程群为准。</small>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
{{template "base/footer" .}}
|
||||
@@ -0,0 +1,92 @@
|
||||
{{/*
|
||||
登录页, 整文件覆盖 Gitea 内置 templates/user/auth/signin.tmpl。
|
||||
|
||||
维护约定:
|
||||
* 上游基线: customization/upstream/<版本>/templates/user/auth/signin.tmpl
|
||||
升级 Gitea 时先 diff 基线, 把上游的结构性改动(新增表单字段/新认证方式)合并回来。
|
||||
* 相对上游的改动只有布局, 逻辑尽量原样搬过来:
|
||||
1) 课程同学走的是「高程统一身份认证」(OIDC), 所以把它放进第一张卡片、配说明文字;
|
||||
卡片正文复用上游的 {{template "user/auth/external_auth_methods" .}},
|
||||
将来新增/更换认证源不用改这个模板。
|
||||
2) 用户名/密码降级为第二张「管理员登录」卡片, 并在正文里写明只有管理员/助教用。
|
||||
3) 不再渲染通行密钥(passkey)区块 —— 上游那块只有 tw-hidden 的元素, 浏览器不支持
|
||||
条件中介时会留下一个空的方框; 服务端已用
|
||||
[service] ENABLE_PASSKEY_AUTHENTICATION = false 关掉该功能。
|
||||
* 只用 Gitea 已编译进 CSS 的 class: Tailwind 工具类是按上游模板裁剪过的,
|
||||
新增 tw-* 前先 grep assets/css/index.css 确认存在(否则不会生效)。
|
||||
* 文案直接写中文(平台只面向中文用户), 表单标签仍走 ctx.Locale.Tr 以便跟随语言设置。
|
||||
*/}}
|
||||
{{template "base/head" .}}
|
||||
<div role="main" aria-label="{{.Title}}" class="page-content user signin">
|
||||
<div class="ui middle very relaxed page grid">
|
||||
{{/* 这些样式与内置模板保持一致, 同时作用于登录/注册/绑定账号页 */}}
|
||||
<div class="column tw-flex tw-flex-col tw-gap-4 tw-max-w-2xl tw-m-auto">
|
||||
<div class="ui container fluid">
|
||||
{{template "base/alert" .}}
|
||||
</div>
|
||||
|
||||
{{$hasExternalAuth := or .OAuth2Providers .EnableOpenIDSignIn .EnableSSPI}}
|
||||
{{if $hasExternalAuth}}
|
||||
<div class="ui container fluid">
|
||||
<h4 class="ui top attached header center">登录 {{AppName}}</h4>
|
||||
<div class="ui attached segment">
|
||||
<p class="tw-text-center tw-m-0">
|
||||
请使用<strong>高程统一身份认证</strong>登录, 账号密码与文档作业网站相同
|
||||
</p>
|
||||
{{template "user/auth/external_auth_methods" .}}
|
||||
</div>
|
||||
</div>
|
||||
{{end}}
|
||||
|
||||
{{if .EnablePasswordSignInForm}}
|
||||
<div class="ui container fluid">
|
||||
<h4 class="ui top attached header center">管理员登录</h4>
|
||||
<div class="ui attached segment">
|
||||
<p class="tw-text-center tw-m-0 tw-text-sm">
|
||||
此入口仅供管理员使用
|
||||
</p>
|
||||
<form class="ui form" action="{{.SignInLink}}" method="post">
|
||||
<div class="required field {{if .Err_UserName}}error{{end}}">
|
||||
<label for="user_name">{{ctx.Locale.Tr "home.uname_holder"}}</label>
|
||||
<input id="user_name" type="text" name="user_name" value="{{.user_name}}" required tabindex="1">
|
||||
</div>
|
||||
{{if not .DisablePassword}}
|
||||
<div class="required field {{if .Err_Password}}error{{end}}">
|
||||
<div class="tw-flex tw-mb-1">
|
||||
<label for="password" class="tw-flex-1">{{ctx.Locale.Tr "password"}}</label>
|
||||
<a href="{{AppSubUrl}}/user/forgot_password" tabindex="4">{{ctx.Locale.Tr "auth.forgot_password"}}</a>
|
||||
</div>
|
||||
<input id="password" name="password" type="password" value="{{.password}}" autocomplete="current-password" required tabindex="2">
|
||||
</div>
|
||||
{{end}}
|
||||
<div class="inline field">
|
||||
<div class="ui checkbox">
|
||||
<label>{{ctx.Locale.Tr "auth.remember_me"}}</label>
|
||||
<input name="remember" type="checkbox" tabindex="5">
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{{template "user/auth/captcha" .}}
|
||||
|
||||
<div class="field">
|
||||
<button class="ui primary button tw-w-full" tabindex="3">
|
||||
{{ctx.Locale.Tr "sign_in"}}
|
||||
</button>
|
||||
</div>
|
||||
</form>
|
||||
</div>
|
||||
</div>
|
||||
{{end}}
|
||||
|
||||
{{if .ShowRegistrationButton}}
|
||||
<div class="ui container fluid">
|
||||
<div class="ui attached segment tw-text-center">
|
||||
<span>{{ctx.Locale.Tr "auth.need_account"}}</span>
|
||||
<a href="{{AppSubUrl}}/user/sign_up">{{ctx.Locale.Tr "auth.sign_up_now"}}</a>
|
||||
</div>
|
||||
</div>
|
||||
{{end}}
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
{{template "base/footer" .}}
|
||||
@@ -0,0 +1,22 @@
|
||||
{{template "base/head" .}}
|
||||
<div role="main" aria-label="{{.Title}}" class="page-content dashboard feeds">
|
||||
{{template "user/dashboard/navbar" .}}
|
||||
{{/* ★ 本课程新增(上游没有这一行): 首页顶部的「本学期答疑入口」卡片。
|
||||
卡片内容在 custom/templates/custom/tjhlp_semester_card.tmpl;
|
||||
升级 Gitea 时先 diff upstream/<版本>/templates/user/dashboard/dashboard.tmpl,
|
||||
确认上游结构变化后把这一行重新插到 navbar 之后即可。 */}}
|
||||
{{template "custom/tjhlp_semester_card" .}}
|
||||
<div class="ui container flex-container">
|
||||
<div class="flex-container-main">
|
||||
{{template "base/alert" .}}
|
||||
{{template "user/heatmap" .}}
|
||||
{{if .Page.Paginater.TotalPages}}
|
||||
{{template "user/dashboard/feeds" .}}
|
||||
{{else}}
|
||||
{{template "user/dashboard/guide" .}}
|
||||
{{end}}
|
||||
</div>
|
||||
{{template "user/dashboard/repolist" .}}
|
||||
</div>
|
||||
</div>
|
||||
{{template "base/footer" .}}
|
||||
Executable
+38
@@ -0,0 +1,38 @@
|
||||
#!/usr/bin/env bash
|
||||
# 拉取指定 Gitea 版本的上游文件快照到 upstream/<版本>/。
|
||||
#
|
||||
# 快照是定制构建的基线: build.py 由它 + overrides/ 生成最终 locale;
|
||||
# templates/ 下我们整文件覆盖的模板也以它为 diff 依据。
|
||||
#
|
||||
# 用法:
|
||||
# customization/fetch-upstream.sh 1.27.3
|
||||
#
|
||||
# 只下载源码包并抽取 upstream-files.txt 列出的文件, 不会保存整份源码。
|
||||
set -euo pipefail
|
||||
|
||||
VERSION="${1:?用法: fetch-upstream.sh <版本, 例如 1.27.3>}"
|
||||
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
DEST="${HERE}/upstream/${VERSION}"
|
||||
URL="https://dl.gitea.com/gitea/${VERSION}/gitea-src-${VERSION}.tar.gz"
|
||||
|
||||
TMP="$(mktemp -d)"
|
||||
trap 'rm -rf "${TMP}"' EXIT
|
||||
|
||||
echo "下载 ${URL}"
|
||||
curl -fsSL -o "${TMP}/src.tar.gz" "${URL}"
|
||||
|
||||
mkdir -p "${DEST}"
|
||||
while read -r path; do
|
||||
[ -z "${path}" ] && continue
|
||||
case "${path}" in \#*) continue ;; esac
|
||||
if ! tar -xzf "${TMP}/src.tar.gz" -C "${TMP}" "gitea-src-${VERSION}/${path}" 2>/dev/null; then
|
||||
echo "✗ 上游不存在该文件(版本里改名/删除了?): ${path}" >&2
|
||||
exit 1
|
||||
fi
|
||||
mkdir -p "${DEST}/$(dirname "${path}")"
|
||||
cp "${TMP}/gitea-src-${VERSION}/${path}" "${DEST}/${path}"
|
||||
echo " ✓ ${path}"
|
||||
done <"${HERE}/upstream-files.txt"
|
||||
|
||||
echo "✓ 快照已更新到 ${DEST}"
|
||||
echo " 下一步: python3 customization/build.py, 然后 diff 上游模板改动"
|
||||
@@ -0,0 +1 @@
|
||||
1.27.3
|
||||
@@ -0,0 +1,16 @@
|
||||
{
|
||||
"_comment": [
|
||||
"精确覆盖: 键名必须存在于同版本上游 locale_zh-CN.json, 否则构建报错。",
|
||||
"在 rules 之后应用, 因此这里写的内容一定是最终结果。",
|
||||
"改动前请对照上游原文; 含占位符(如 %s / %[1]s / %d / <strong>%d</strong>)的条目必须保留占位符。"
|
||||
],
|
||||
"overrides": {
|
||||
"repo.activity.active_issues_count_1": "共 <strong>%d</strong> 个 Issue",
|
||||
"repo.activity.active_issues_count_n": "共 <strong>%d</strong> 个 Issue",
|
||||
"repo.activity.title.issues_1": "%d 个 Issue",
|
||||
"repo.activity.title.issues_n": "%d 个 Issue",
|
||||
"repo.milestones.filter_sort.most_issues": "按 Issue 数量从多到少",
|
||||
"repo.milestones.filter_sort.least_issues": "按 Issue 数量从少到多",
|
||||
"admin.repos.issues": "Issue 数"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"_comment": [
|
||||
"按顺序对所有 zh-CN 译文做字面替换的规则。",
|
||||
"适合「全站统一术语」这类批量修改, 新增术语时在这里加一条即可。",
|
||||
"替换按数组顺序依次执行; 需要精修的具体条目请放到 locale_zh-CN.json(精确覆盖优先于本文件)。"
|
||||
],
|
||||
"rules": [
|
||||
{
|
||||
"note": "Issue 不译为「工单」, 直接沿用英文",
|
||||
"from": "工单",
|
||||
"to": "Issue"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,115 @@
|
||||
# =============================================================================
|
||||
# TJHLP 定制预览实例(与生产完全隔离, 只绑定回环)
|
||||
#
|
||||
# 目的: 在不动生产容器/数据的前提下, 用【与生产相同版本】的官方镜像验证
|
||||
# customization/custom 下的模板、文案、静态资源效果。
|
||||
#
|
||||
# 与生产(deploy/compose.yaml)的区别:
|
||||
# * 项目名 gitea-preview, 容器名 gitea-preview, 端口 127.0.0.1:2081
|
||||
# * 数据库用 sqlite(预览不需要 PostgreSQL)
|
||||
# * 数据目录 preview/data(gitignore), 删除即重置
|
||||
# * RUN_MODE=dev: 修改 custom/ 下的模板或语言文件后自动热加载, 无需重启
|
||||
# * 把 customization/custom 只读挂载到容器的 GITEA_CUSTOM/custom
|
||||
#
|
||||
# 用法(见 preview.sh):
|
||||
# ./preview.sh up 启动
|
||||
# ./preview.sh logs 看日志
|
||||
# ./preview.sh down 停止
|
||||
# ./preview.sh reset 停止并清空预览数据
|
||||
# =============================================================================
|
||||
|
||||
name: gitea-preview
|
||||
|
||||
services:
|
||||
gitea:
|
||||
image: docker.gitea.com/gitea:${GITEA_VERSION:-1.27.3}
|
||||
container_name: gitea-preview
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
# 与宿主当前用户对齐, 让 ./data 的属主正确(见 preview.sh)
|
||||
USER_UID: ${PREVIEW_UID:-1001}
|
||||
USER_GID: ${PREVIEW_GID:-1001}
|
||||
TZ: ${TZ:-Asia/Shanghai}
|
||||
|
||||
APP_NAME: 同济高程-答疑平台(预览)
|
||||
# dev(默认): 语言文件改动自动热加载(实测), 模板报错也不致命 —— 改文案方便;
|
||||
# prod: 与生产完全一致, 任何改动都要 ./preview.sh reload。
|
||||
# 注意: 模板是启动时编译的, dev 下改模板同样要重启(官方文档也是这么说的)。
|
||||
RUN_MODE: ${PREVIEW_RUN_MODE:-dev}
|
||||
|
||||
# --- 数据库: sqlite(预览专用) -------------------------------------
|
||||
GITEA__database__DB_TYPE: sqlite3
|
||||
GITEA__database__PATH: /data/gitea/gitea.db
|
||||
|
||||
# --- 服务地址 ------------------------------------------------------
|
||||
GITEA__server__PROTOCOL: http
|
||||
GITEA__server__DOMAIN: 127.0.0.1
|
||||
GITEA__server__ROOT_URL: http://127.0.0.1:${PREVIEW_PORT:-2081}/
|
||||
GITEA__server__HTTP_ADDR: 0.0.0.0
|
||||
GITEA__server__HTTP_PORT: "3000"
|
||||
GITEA__server__DISABLE_SSH: "true"
|
||||
GITEA__server__LFS_START_SERVER: "true"
|
||||
GITEA__server__OFFLINE_MODE: "false"
|
||||
|
||||
# --- 安全: 跳过安装向导; 密钥不在这里指定 -------------------------
|
||||
# LFS_JWT_SECRET / INTERNAL_TOKEN / JWT_SECRET 留空时 Gitea 会自己生成
|
||||
# 并写回 /data/gitea/conf/app.ini(可写), 重启后保持不变。
|
||||
GITEA__security__INSTALL_LOCK: "true"
|
||||
|
||||
# --- 注册 / 登录 ---------------------------------------------------
|
||||
GITEA__service__DISABLE_REGISTRATION: "false"
|
||||
GITEA__service__ENABLE_CAPTCHA: "false"
|
||||
GITEA__service__REQUIRE_SIGNIN_VIEW: "false"
|
||||
# 不做通行密钥(WebAuthn): 上游登录页那块只有 tw-hidden 元素, 浏览器不支持条件中介时
|
||||
# 会留下一个空的方框; 关掉后区块不再渲染, 登录页也不会出现 passkey 入口。
|
||||
GITEA__service__ENABLE_PASSKEY_AUTHENTICATION: "false"
|
||||
GITEA__mailer__ENABLED: "false"
|
||||
|
||||
# --- 出站代理: 显式给值挡掉自动注入, 默认不用代理 ---------------------
|
||||
# compose 会把宿主 shell 的 http_proxy(本机是 127.0.0.1:7890, 在容器里指向
|
||||
# 容器自己)自动注入; 生产上这会直接让 OIDC discovery 失败(登录 404)。
|
||||
# 容器直连外网本身是通的(实测), 不需要代理; 理由见 deploy/compose.yaml 同位置注释。
|
||||
HTTP_PROXY: ${GITEA_HTTP_PROXY:-}
|
||||
HTTPS_PROXY: ${GITEA_HTTPS_PROXY:-}
|
||||
http_proxy: ${GITEA_HTTP_PROXY:-}
|
||||
https_proxy: ${GITEA_HTTPS_PROXY:-}
|
||||
NO_PROXY: ${GITEA_NO_PROXY:-localhost,127.0.0.1,::1,10.80.42.185,.local,.internal}
|
||||
no_proxy: ${GITEA_NO_PROXY:-localhost,127.0.0.1,::1,10.80.42.185,.local,.internal}
|
||||
|
||||
# --- 站点元信息与页脚: 去掉 Gitea 自我推销 -------------------------
|
||||
# 段名里的点要写成 _0X2E_ (Gitea 的 GITEA__section__KEY 编码规则)
|
||||
GITEA__ui_0X2E_meta__AUTHOR: 同济大学高级语言程序设计课程
|
||||
GITEA__ui_0X2E_meta__DESCRIPTION: 同济大学高级语言程序设计课程答疑平台
|
||||
GITEA__ui_0X2E_meta__KEYWORDS: 同济大学,高级语言程序设计,答疑,Issue
|
||||
GITEA__other__SHOW_FOOTER_POWERED_BY: "false"
|
||||
GITEA__other__SHOW_FOOTER_VERSION: "false"
|
||||
|
||||
# --- 显示名称: 与生产一致, Issue 显示姓名而不是学号 ----------------
|
||||
# 说明见 deploy/compose.yaml 同位置。这里给上才能让预览里验证
|
||||
# 「发布者/回答者显示姓名」的效果。
|
||||
GITEA__ui__DEFAULT_SHOW_FULL_NAME: "true"
|
||||
|
||||
GITEA__log__MODE: console
|
||||
GITEA__log__LEVEL: ${GITEA_LOG_LEVEL:-info}
|
||||
|
||||
volumes:
|
||||
- ./data:/data
|
||||
# ★ 官方镜像里 GITEA_CUSTOM=/data/gitea, 所以定制文件对应
|
||||
# /data/gitea/{templates,public,options}, 而不是 /data/gitea/custom
|
||||
# (后者是源码/二进制安装时 WorkPath/custom 的习惯写法)。
|
||||
# 分开挂三个子目录: 既只读覆盖定制内容, 又不遮住同级的 conf/、log/。
|
||||
- ../custom/templates:/data/gitea/templates:ro
|
||||
- ../custom/public:/data/gitea/public:ro
|
||||
- ../custom/options:/data/gitea/options:ro
|
||||
- /etc/localtime:/etc/localtime:ro
|
||||
|
||||
ports:
|
||||
# 只绑定回环, 预览实例不对内网/外网暴露
|
||||
- "127.0.0.1:${PREVIEW_PORT:-2081}:3000"
|
||||
|
||||
healthcheck:
|
||||
test: ["CMD", "curl", "-fsS", "http://127.0.0.1:3000/api/healthz"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 10
|
||||
start_period: 60s
|
||||
Executable
+198
@@ -0,0 +1,198 @@
|
||||
#!/usr/bin/env bash
|
||||
# 预览实例管理脚本: 见 compose.yaml 顶部说明。
|
||||
#
|
||||
# ./preview.sh up 构建定制产物并启动预览 (http://127.0.0.1:2081)
|
||||
# ./preview.sh down 停止预览(保留数据)
|
||||
# ./preview.sh reset 停止并删除预览数据(下次全新安装)
|
||||
# ./preview.sh logs 跟踪日志
|
||||
# ./preview.sh ps 查看状态
|
||||
# ./preview.sh shell 进入容器
|
||||
# ./preview.sh admin 在预览实例里建一个管理员(用于验证登录后的页面)
|
||||
# ./preview.sh semester 造一个学期组织(含 general 仓库), 用于看首页的答疑入口卡片
|
||||
# ./preview.sh check 构建校验 + 首页文案/页脚/元信息抽查
|
||||
#
|
||||
# 说明: 本机 docker 需要 docker 组权限; 当前 shell 没有时会自动改用
|
||||
# `sg docker -c ...`(sg 读 /etc/group 的成员关系, 不需要 sudo)。
|
||||
set -euo pipefail
|
||||
|
||||
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
ROOT="$(cd "${HERE}/.." && pwd)"
|
||||
COMPOSE_FILE="${HERE}/compose.yaml"
|
||||
PORT="${PREVIEW_PORT:-2081}"
|
||||
BASE_URL="http://127.0.0.1:${PORT}"
|
||||
export PREVIEW_UID="$(id -u)"
|
||||
export PREVIEW_GID="$(id -g)"
|
||||
|
||||
# 是否需要套 sg docker
|
||||
if docker info >/dev/null 2>&1; then
|
||||
compose() { docker compose -f "${COMPOSE_FILE}" "$@"; }
|
||||
elif command -v sg >/dev/null 2>&1 && sg docker -c 'docker info' >/dev/null 2>&1; then
|
||||
compose() { sg docker -c "docker compose -f '${COMPOSE_FILE}' $*"; }
|
||||
else
|
||||
echo "✗ 当前用户没有 docker 权限(既不能直连, 也不能通过 docker 组)" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
prepare() {
|
||||
# 生成定制产物(语言文件等)
|
||||
python3 "${ROOT}/build.py" --quiet
|
||||
# 预建数据目录: 属主等于当前用户, 容器 entrypoint 就不会对只读挂载做 chown。
|
||||
# .ssh 必须由我们建: 否则容器以 root 建出 0700 目录, 降权后的 gitea 进程
|
||||
# 写不了 authorized_keys。
|
||||
mkdir -p "${HERE}/data/gitea/conf" "${HERE}/data/git/.ssh" "${HERE}/data/ssh"
|
||||
chmod 700 "${HERE}/data/git/.ssh"
|
||||
}
|
||||
|
||||
case "${1:-}" in
|
||||
up)
|
||||
prepare
|
||||
compose up -d
|
||||
echo "预览地址: ${BASE_URL} (数据目录: ${HERE}/data)"
|
||||
echo "首次启动约需 10~30 秒; 用 ./preview.sh logs 观察进度"
|
||||
;;
|
||||
down)
|
||||
compose down
|
||||
;;
|
||||
reload)
|
||||
# 模板改完必须重启才生效(prod/dev 都一样); 语言文件在 dev 下会自动热加载
|
||||
python3 "${ROOT}/build.py" --quiet
|
||||
compose restart gitea
|
||||
echo "已重启, 预览地址: ${BASE_URL}"
|
||||
;;
|
||||
reset)
|
||||
compose down
|
||||
if ! rm -rf "${HERE}/data" 2>/dev/null; then
|
||||
# 容器可能以 root 身份建过 data/git/.ssh(0700), 宿主用户删不掉;
|
||||
# 用一次性 root 容器清掉再删(正常流程不会走到这里, 见 prepare 的说明)。
|
||||
compose run --rm -T --user 0 --entrypoint /bin/sh gitea -c 'rm -rf /data/git /data/ssh' >/dev/null
|
||||
rm -rf "${HERE}/data"
|
||||
fi
|
||||
echo "已清空预览数据"
|
||||
;;
|
||||
logs)
|
||||
compose logs -f --tail=100
|
||||
;;
|
||||
ps)
|
||||
compose ps
|
||||
;;
|
||||
shell)
|
||||
compose exec gitea bash
|
||||
;;
|
||||
admin)
|
||||
USERNAME="${2:-previewadmin}"
|
||||
PASSWORD="${3:-previewadmin123}"
|
||||
# -u git: gitea 命令拒绝以 root 运行
|
||||
compose exec -T -u git gitea gitea admin user create \
|
||||
--username "${USERNAME}" --password "${PASSWORD}" \
|
||||
--email "${USERNAME}@example.com" --admin --must-change-password=false
|
||||
echo "管理员: ${USERNAME} / ${PASSWORD}"
|
||||
;;
|
||||
semester)
|
||||
# 造一个学期组织 + general 仓库, 用来在预览里验证首页(登录后)的答疑入口卡片。
|
||||
# 幂等: 已存在就跳过。默认建 tjhlp-26271(2026-2027 学年第一学期 的命名),
|
||||
# 想验证"只认最新学期/不认旧命名"可以再建几个:
|
||||
# ./preview.sh semester previewadmin previewadmin123 tjhlp-25261
|
||||
# ./preview.sh semester previewadmin previewadmin123 tjhlp-2026s
|
||||
USERNAME="${2:-previewadmin}"
|
||||
PASSWORD="${3:-previewadmin123}"
|
||||
ORG="${4:-tjhlp-26271}"
|
||||
api() { curl -fsS --noproxy '*' -u "${USERNAME}:${PASSWORD}" -H 'Content-Type: application/json' "$@"; }
|
||||
if api "${BASE_URL}/api/v1/orgs/${ORG}" >/dev/null 2>&1; then
|
||||
echo "组织 ${ORG} 已存在, 跳过创建"
|
||||
else
|
||||
api -X POST -d "{\"username\":\"${ORG}\",\"full_name\":\"${ORG}\"}" "${BASE_URL}/api/v1/orgs" >/dev/null
|
||||
echo "已创建组织 ${ORG}(创建者即成员, 也就是 ${USERNAME})"
|
||||
fi
|
||||
if api "${BASE_URL}/api/v1/repos/${ORG}/general" >/dev/null 2>&1; then
|
||||
echo "仓库 ${ORG}/general 已存在"
|
||||
else
|
||||
api -X POST -d '{"name":"general","auto_init":true,"private":true}' \
|
||||
"${BASE_URL}/api/v1/orgs/${ORG}/repos" >/dev/null
|
||||
echo "已创建仓库 ${ORG}/general"
|
||||
fi
|
||||
echo "用 ${USERNAME} 登录 ${BASE_URL} 看首页卡片; 期望按钮指向 ${ORG}/general/issues"
|
||||
;;
|
||||
check)
|
||||
python3 "${ROOT}/build.py" --check --quiet
|
||||
fail=0
|
||||
ok() { echo "✓ $1"; }
|
||||
bad() {
|
||||
echo "✗ $1"
|
||||
fail=1
|
||||
}
|
||||
|
||||
html="$(mktemp)"
|
||||
trap 'rm -f "${html}"' EXIT
|
||||
curl -fsS "${BASE_URL}/" -o "${html}"
|
||||
|
||||
grep -q "先搜索,再提问" "${html}" && ok "首页用的是定制模板 home.tmpl" || bad "首页没有定制模板的内容"
|
||||
grep -q "https://cpp.tongji.sh/Website/qa/ask/" "${html}" &&
|
||||
ok "导航栏/首页已指向官网提问指南(/Website/qa/ask/)" ||
|
||||
bad "没找到官网提问指南链接(页面还是旧模板? 模板改动要重启 gitea 才生效)"
|
||||
! grep -q "painless\|极易搭建\|Easy to install\|Cross-platform" "${html}" &&
|
||||
ok "首页已无 Gitea 功能介绍" || bad "首页仍有 Gitea 功能介绍文案"
|
||||
! grep -qi "powered by" "${html}" && ok "页脚已无 Powered by Gitea" || bad "页脚仍有 Powered by"
|
||||
! grep -q "docs.gitea.com" "${html}" && ok "页面已无 docs.gitea.com 外链" || bad "仍有 docs.gitea.com 外链"
|
||||
grep -q 'name="description" content="同济大学高级语言程序设计课程答疑平台"' "${html}" &&
|
||||
ok "meta description 已替换" || bad "meta description 未替换"
|
||||
|
||||
# 站内提问指南页已按决定删除(提问指南只在官网保留一份)
|
||||
! curl -fsS -o /dev/null "${BASE_URL}/assets/tjhlp/ask-guide.html" 2>/dev/null &&
|
||||
ok "平台内提问指南页已删除" || bad "平台内还留着 ask-guide.html"
|
||||
|
||||
# --- 与课程官网的联动 -------------------------------------------------
|
||||
grep -q "https://cpp.tongji.sh/Website/" "${html}" &&
|
||||
ok "首页/导航栏已链接课程官网" || bad "首页没有课程官网链接"
|
||||
grep -q "https://cpp.tongji.sh/Website/qa/ask/" "${html}" &&
|
||||
ok "首页已链接官网提问指南" || bad "首页没有官网提问指南链接"
|
||||
! grep -q "Website/ask-question/\|Website/faq/\|Website/contact\"" "${html}" &&
|
||||
ok "没有指向官网已迁移/失效的旧地址" ||
|
||||
bad "仍有旧地址(ask-question / faq / contact 无 .html)"
|
||||
! grep -rq "example.com" "${ROOT}/../issue-templates/" &&
|
||||
ok "Issue 模板已无 example.com 占位链接" || bad "Issue 模板里仍有 example.com"
|
||||
|
||||
! grep -q "工单" "${ROOT}/custom/options/locale/locale_zh-CN.json" &&
|
||||
ok "生成的 zh-CN 语言文件已无「工单」" || bad "语言文件里仍有「工单」"
|
||||
|
||||
# --- 登录页 -----------------------------------------------------------
|
||||
login="$(mktemp)"
|
||||
curl -fsS -H 'Accept-Language: zh-CN' "${BASE_URL}/user/login" -o "${login}"
|
||||
grep -q "管理员登录" "${login}" &&
|
||||
ok "登录页有独立的「管理员登录」卡片" || bad "登录页缺少管理员登录卡片"
|
||||
! grep -q "webauthn-error\|signin-passkey" "${login}" &&
|
||||
ok "登录页已无空的通行密钥(WebAuthn)方框" || bad "登录页仍有通行密钥区块"
|
||||
grep -q 'id="external-login-navigator"' "${login}" ||
|
||||
echo " (提示: 预览未配置认证源, 登录页不显示统一身份认证按钮; 见 customization/README.md 3.4)"
|
||||
rm -f "${login}"
|
||||
|
||||
# --- 首页(登录后)的「本学期答疑入口」卡片 -----------------------------
|
||||
# 预览里没有管理员/学期组织时会跳过(只提示), 不算失败。
|
||||
cj="$(mktemp)"
|
||||
dash="$(mktemp)"
|
||||
trap 'rm -f "${html}" "${cj}" "${dash}"' EXIT
|
||||
curl -fsS -c "${cj}" -b "${cj}" -X POST \
|
||||
--data-urlencode "user_name=${PREVIEW_ADMIN_USER:-previewadmin}" \
|
||||
--data-urlencode "password=${PREVIEW_ADMIN_PASSWORD:-previewadmin123}" \
|
||||
"${BASE_URL}/user/login" -o /dev/null || true
|
||||
curl -fsS -b "${cj}" "${BASE_URL}/" -o "${dash}" || true
|
||||
if ! grep -q 'class="page-content dashboard' "${dash}"; then
|
||||
echo " (提示: 预览里没有可登录的 previewadmin; 跑 ./preview.sh admin 后再检查登录后页面)"
|
||||
elif grep -q "本学期答疑入口" "${dash}"; then
|
||||
ok "首页(登录后)有「本学期答疑入口」卡片"
|
||||
grep -q "/tjhlp-[0-9]\{5\}/general/issues" "${dash}" &&
|
||||
ok "卡片按钮指向 <学期组织>/general/issues" ||
|
||||
bad "卡片按钮链接不是 <学期组织>/general/issues"
|
||||
grep -q "min-height:33vh" "${dash}" &&
|
||||
ok "卡片高度约 1/3 屏(33vh)" || bad "卡片没有 33vh 高度"
|
||||
else
|
||||
echo " (提示: 当前登录用户不属于任何学期组织 => 卡片不显示; 跑 ./preview.sh semester 造一个)"
|
||||
fi
|
||||
|
||||
[ "${fail}" = 0 ] && echo "全部检查通过" || echo "存在检查未通过项"
|
||||
exit "${fail}"
|
||||
;;
|
||||
*)
|
||||
sed -n '2,18p' "$0"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
@@ -0,0 +1,11 @@
|
||||
# 需要留快照的上游文件(相对 gitea 源码根目录), 每行一个, # 开头为注释。
|
||||
#
|
||||
# 什么时候往这里加一行:
|
||||
# * build.py 生成的 locale 基线(必须)
|
||||
# * custom/templates/ 下我们整文件覆盖的内置模板(必须, 否则升级时没有 diff 依据)
|
||||
# * custom/options/ 下我们覆盖的内置数据文件(如 gitignore/label)
|
||||
options/locale/locale_zh-CN.json
|
||||
templates/home.tmpl
|
||||
templates/base/head_navbar.tmpl
|
||||
templates/user/auth/signin.tmpl
|
||||
templates/user/dashboard/dashboard.tmpl
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,182 @@
|
||||
<nav id="navbar" aria-label="{{ctx.Locale.Tr "aria.navbar"}}">
|
||||
<div class="navbar-left">
|
||||
<!-- the logo -->
|
||||
<a class="item" id="navbar-logo" href="{{AppSubUrl}}/" aria-label="{{if .IsSigned}}{{ctx.Locale.Tr "dashboard"}}{{else}}{{ctx.Locale.Tr "home_title"}}{{end}}">
|
||||
<img width="30" height="30" src="{{AssetUrlPrefix}}/img/logo.svg" alt="{{ctx.Locale.Tr "logo"}}" aria-hidden="true">
|
||||
</a>
|
||||
|
||||
<!-- mobile right menu, it must be here because in mobile view, each item is a flex column, the first item is a full row column -->
|
||||
<div class="ui secondary menu navbar-mobile-right only-mobile">
|
||||
{{template "base/head_navbar_icons" dict "PageGlobalData" .PageGlobalData}}
|
||||
<button class="item ui icon mini button tw-m-0" id="navbar-expand-toggle" aria-label="{{ctx.Locale.Tr "home.nav_menu"}}">{{svg "octicon-three-bars"}}</button>
|
||||
</div>
|
||||
|
||||
<!-- navbar links non-mobile -->
|
||||
{{if and .IsSigned .MustChangePassword}}
|
||||
{{/* No links */}}
|
||||
{{else if .IsSigned}}
|
||||
{{if not ctx.Consts.RepoUnitTypeIssues.UnitGlobalDisabled}}
|
||||
<a class="item{{if .PageIsIssues}} active{{end}}" href="{{AppSubUrl}}/issues">{{ctx.Locale.Tr "issues"}}</a>
|
||||
{{end}}
|
||||
{{if not ctx.Consts.RepoUnitTypePullRequests.UnitGlobalDisabled}}
|
||||
<a class="item{{if .PageIsPulls}} active{{end}}" href="{{AppSubUrl}}/pulls">{{ctx.Locale.Tr "pull_requests"}}</a>
|
||||
{{end}}
|
||||
{{if not (and ctx.Consts.RepoUnitTypeIssues.UnitGlobalDisabled ctx.Consts.RepoUnitTypePullRequests.UnitGlobalDisabled)}}
|
||||
{{if .ShowMilestonesDashboardPage}}
|
||||
<a class="item{{if .PageIsMilestonesDashboard}} active{{end}}" href="{{AppSubUrl}}/milestones">{{ctx.Locale.Tr "milestones"}}</a>
|
||||
{{end}}
|
||||
{{end}}
|
||||
<a class="item{{if .PageIsExplore}} active{{end}}" href="{{AppSubUrl}}/explore/repos">{{ctx.Locale.Tr "explore_title"}}</a>
|
||||
{{else if .IsLandingPageOrganizations}}
|
||||
<a class="item{{if .PageIsExplore}} active{{end}}" href="{{AppSubUrl}}/explore/organizations">{{ctx.Locale.Tr "explore_title"}}</a>
|
||||
{{else}}
|
||||
<a class="item{{if .PageIsExplore}} active{{end}}" href="{{AppSubUrl}}/explore/repos">{{ctx.Locale.Tr "explore_title"}}</a>
|
||||
{{end}}
|
||||
|
||||
{{template "custom/extra_links" .}}
|
||||
|
||||
{{if not .IsSigned}}
|
||||
<a class="item" target="_blank" href="https://docs.gitea.com">{{ctx.Locale.Tr "help"}}</a>
|
||||
{{end}}
|
||||
</div>
|
||||
|
||||
<!-- the full dropdown menus -->
|
||||
<div class="navbar-right">
|
||||
{{if and .IsSigned .MustChangePassword}}
|
||||
<div class="ui dropdown jump item" data-tooltip-content="{{ctx.Locale.Tr "user_profile_and_more"}}">
|
||||
<span class="text">
|
||||
{{ctx.AvatarUtils.Avatar .SignedUser 24 "tw-mr-1"}}
|
||||
<span class="only-mobile">{{.SignedUser.Name}}</span>
|
||||
<span class="not-mobile flex-text-block">{{svg "octicon-triangle-down"}}</span>
|
||||
</span>
|
||||
<div class="menu user-menu">
|
||||
<div class="header">
|
||||
{{ctx.Locale.Tr "signed_in_as"}} <strong>{{.SignedUser.Name}}</strong>
|
||||
</div>
|
||||
|
||||
<div class="divider"></div>
|
||||
<a class="item" href="{{AppSubUrl}}/user/logout">
|
||||
{{svg "octicon-sign-out"}}
|
||||
{{ctx.Locale.Tr "sign_out"}}
|
||||
</a>
|
||||
</div><!-- end content avatar menu -->
|
||||
</div><!-- end dropdown avatar menu -->
|
||||
{{else if .IsSigned}}
|
||||
{{template "base/head_navbar_icons" dict "ItemExtraClass" "not-mobile" "PageGlobalData" .PageGlobalData}}
|
||||
<div class="ui dropdown jump item" data-tooltip-content="{{ctx.Locale.Tr "create_new"}}">
|
||||
<span class="flex-text-block">
|
||||
{{svg "octicon-plus"}}
|
||||
<span class="not-mobile flex-text-block">{{svg "octicon-triangle-down"}}</span>
|
||||
<span class="only-mobile">{{ctx.Locale.Tr "create_new"}}</span>
|
||||
</span>
|
||||
<div class="menu">
|
||||
<a class="item" href="{{AppSubUrl}}/repo/create">
|
||||
{{svg "octicon-plus"}} {{ctx.Locale.Tr "new_repo"}}
|
||||
</a>
|
||||
{{if not .DisableMigrations}}
|
||||
<a class="item" href="{{AppSubUrl}}/repo/migrate">
|
||||
{{svg "octicon-repo-push"}} {{ctx.Locale.Tr "new_migrate"}}
|
||||
</a>
|
||||
{{end}}
|
||||
{{if .SignedUser.CanCreateOrganization}}
|
||||
<a class="item" href="{{AppSubUrl}}/org/create">
|
||||
{{svg "octicon-organization"}} {{ctx.Locale.Tr "new_org"}}
|
||||
</a>
|
||||
{{end}}
|
||||
</div><!-- end content create new menu -->
|
||||
</div><!-- end dropdown menu create new -->
|
||||
|
||||
<div class="ui dropdown jump item" data-tooltip-content="{{ctx.Locale.Tr "user_profile_and_more"}}">
|
||||
<span class="text tw-flex tw-items-center">
|
||||
<span class="navbar-avatar">
|
||||
{{ctx.AvatarUtils.Avatar .SignedUser 24 "tw-mr-2"}}
|
||||
{{if .IsAdmin}}{{svg "octicon-shield-check" 16 "navbar-admin-badge"}}{{end}}
|
||||
</span>
|
||||
<span class="only-mobile">{{.SignedUser.Name}}</span>
|
||||
<span class="not-mobile flex-text-block">{{svg "octicon-triangle-down"}}</span>
|
||||
</span>
|
||||
<div class="menu user-menu">
|
||||
<div class="header">
|
||||
{{ctx.Locale.Tr "signed_in_as"}} <strong>{{.SignedUser.Name}}</strong>
|
||||
</div>
|
||||
|
||||
<div class="divider"></div>
|
||||
<a class="item" href="{{.SignedUser.HomeLink}}">
|
||||
{{svg "octicon-person"}}
|
||||
{{ctx.Locale.Tr "your_profile"}}
|
||||
</a>
|
||||
{{if not .DisableStars}}
|
||||
<a class="item" href="{{.SignedUser.HomeLink}}?tab=stars">
|
||||
{{svg "octicon-star"}}
|
||||
{{ctx.Locale.Tr "your_starred"}}
|
||||
</a>
|
||||
{{end}}
|
||||
<a class="item" href="{{AppSubUrl}}/notifications/subscriptions">
|
||||
{{svg "octicon-bell"}}
|
||||
{{ctx.Locale.Tr "notification.subscriptions"}}
|
||||
</a>
|
||||
<a class="{{if .PageIsUserSettings}}active {{end}}item" href="{{AppSubUrl}}/user/settings">
|
||||
{{svg "octicon-tools"}}
|
||||
{{ctx.Locale.Tr "your_settings"}}
|
||||
</a>
|
||||
<a class="item" target="_blank" href="https://docs.gitea.com">
|
||||
{{svg "octicon-question"}}
|
||||
{{ctx.Locale.Tr "help"}}
|
||||
</a>
|
||||
{{if .IsAdmin}}
|
||||
<div class="divider"></div>
|
||||
<a class="{{if .PageIsAdmin}}active {{end}}item" href="{{AppSubUrl}}/-/admin">
|
||||
{{svg "octicon-server"}}
|
||||
{{ctx.Locale.Tr "admin_panel"}}
|
||||
</a>
|
||||
{{end}}
|
||||
<div class="divider"></div>
|
||||
<a class="item" href="{{AppSubUrl}}/user/logout">
|
||||
{{svg "octicon-sign-out"}}
|
||||
{{ctx.Locale.Tr "sign_out"}}
|
||||
</a>
|
||||
</div><!-- end content avatar menu -->
|
||||
</div><!-- end dropdown avatar menu -->
|
||||
{{else}}
|
||||
{{if .ShowRegistrationButton}}
|
||||
<a class="item{{if .PageIsSignUp}} active{{end}}" href="{{AppSubUrl}}/user/sign_up">
|
||||
{{svg "octicon-person"}}
|
||||
<span class="tw-ml-1">{{ctx.Locale.Tr "register"}}</span>
|
||||
</a>
|
||||
{{end}}
|
||||
<a class="item{{if .PageIsSignIn}} active{{end}}" rel="nofollow" href="{{AppSubUrl}}/user/login">
|
||||
{{svg "octicon-sign-in"}}
|
||||
<span class="tw-ml-1">{{ctx.Locale.Tr "sign_in"}}</span>
|
||||
</a>
|
||||
{{end}}
|
||||
</div><!-- end full right menu -->
|
||||
|
||||
{{$activeStopwatch := and .PageGlobalData (call .PageGlobalData.GetActiveStopwatch)}}
|
||||
{{if $activeStopwatch}}
|
||||
<div class="active-stopwatch-popup tippy-target">
|
||||
<div class="flex-text-block tw-p-3">
|
||||
<a class="stopwatch-link flex-text-block muted" href="{{$activeStopwatch.IssueLink}}">
|
||||
{{svg "octicon-issue-opened" 16}}
|
||||
<span class="stopwatch-issue">{{$activeStopwatch.RepoSlug}}#{{$activeStopwatch.IssueIndex}}</span>
|
||||
</a>
|
||||
<div class="tw-flex tw-gap-1">
|
||||
<form class="stopwatch-commit form-fetch-action" method="post" action="{{$activeStopwatch.IssueLink}}/times/stopwatch/stop">
|
||||
<button
|
||||
type="submit"
|
||||
class="ui button mini compact basic icon tw-mr-0"
|
||||
data-tooltip-content="{{ctx.Locale.Tr "repo.issues.stop_tracking"}}"
|
||||
>{{svg "octicon-square-fill"}}</button>
|
||||
</form>
|
||||
<form class="stopwatch-cancel form-fetch-action" method="post" action="{{$activeStopwatch.IssueLink}}/times/stopwatch/cancel">
|
||||
<button
|
||||
type="submit"
|
||||
class="ui button mini compact basic icon tw-mr-0"
|
||||
data-tooltip-content="{{ctx.Locale.Tr "repo.issues.cancel_tracking"}}"
|
||||
>{{svg "octicon-trash"}}</button>
|
||||
</form>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
{{end}}
|
||||
</nav>
|
||||
{{template "base/head_banner"}}
|
||||
@@ -0,0 +1,51 @@
|
||||
{{template "base/head" .}}
|
||||
<div role="main" aria-label="{{if .IsSigned}}{{ctx.Locale.Tr "dashboard"}}{{else}}{{ctx.Locale.Tr "home_title"}}{{end}}" class="page-content home">
|
||||
<div class="tw-mb-8 tw-px-8">
|
||||
<div class="center">
|
||||
<img class="logo" width="220" height="220" src="{{AssetUrlPrefix}}/img/logo.svg" alt="{{ctx.Locale.Tr "logo"}}">
|
||||
<div class="hero">
|
||||
<h1 class="ui icon header title tw-text-balance">
|
||||
{{AppName}}
|
||||
</h1>
|
||||
<h2 class="tw-text-balance">{{ctx.Locale.Tr "startpage.app_desc"}}</h2>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="ui stackable middle very relaxed page grid">
|
||||
<div class="eight wide center column">
|
||||
<h1 class="hero ui icon header">
|
||||
{{svg "octicon-flame"}} {{ctx.Locale.Tr "startpage.install"}}
|
||||
</h1>
|
||||
<p class="large tw-text-balance">
|
||||
{{ctx.Locale.Tr "startpage.install_desc" "https://docs.gitea.com/installation/install-from-binary" "https://github.com/go-gitea/gitea/tree/master/docker" "https://docs.gitea.com/installation/install-from-package"}}
|
||||
</p>
|
||||
</div>
|
||||
<div class="eight wide center column">
|
||||
<h1 class="hero ui icon header">
|
||||
{{svg "octicon-device-desktop"}} {{ctx.Locale.Tr "startpage.platform"}}
|
||||
</h1>
|
||||
<p class="large tw-text-balance">
|
||||
{{ctx.Locale.Tr "startpage.platform_desc" "https://go.dev/"}}
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="ui stackable middle very relaxed page grid">
|
||||
<div class="eight wide center column">
|
||||
<h1 class="hero ui icon header">
|
||||
{{svg "octicon-rocket"}} {{ctx.Locale.Tr "startpage.lightweight"}}
|
||||
</h1>
|
||||
<p class="large tw-text-balance">
|
||||
{{ctx.Locale.Tr "startpage.lightweight_desc"}}
|
||||
</p>
|
||||
</div>
|
||||
<div class="eight wide center column">
|
||||
<h1 class="hero ui icon header">
|
||||
{{svg "octicon-code"}} {{ctx.Locale.Tr "startpage.license"}}
|
||||
</h1>
|
||||
<p class="large tw-text-balance">
|
||||
{{ctx.Locale.Tr "startpage.license_desc" "https://gitea.dev" "gitea.dev" "https://github.com/go-gitea/gitea"}}
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
{{template "base/footer" .}}
|
||||
@@ -0,0 +1,10 @@
|
||||
{{template "base/head" .}}
|
||||
<div role="main" aria-label="{{.Title}}" class="page-content user signin{{if .LinkAccountMode}} icon{{end}}">
|
||||
<div class="ui middle very relaxed page grid">
|
||||
{{/* these styles are quite tricky and should also apply to the signup and link_account pages */}}
|
||||
<div class="column tw-flex tw-flex-col tw-gap-4 tw-max-w-2xl tw-m-auto">
|
||||
{{template "user/auth/signin_inner" .}}
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
{{template "base/footer" .}}
|
||||
@@ -0,0 +1,17 @@
|
||||
{{template "base/head" .}}
|
||||
<div role="main" aria-label="{{.Title}}" class="page-content dashboard feeds">
|
||||
{{template "user/dashboard/navbar" .}}
|
||||
<div class="ui container flex-container">
|
||||
<div class="flex-container-main">
|
||||
{{template "base/alert" .}}
|
||||
{{template "user/heatmap" .}}
|
||||
{{if .Page.Paginater.TotalPages}}
|
||||
{{template "user/dashboard/feeds" .}}
|
||||
{{else}}
|
||||
{{template "user/dashboard/guide" .}}
|
||||
{{end}}
|
||||
</div>
|
||||
{{template "user/dashboard/repolist" .}}
|
||||
</div>
|
||||
</div>
|
||||
{{template "base/footer" .}}
|
||||
@@ -0,0 +1,187 @@
|
||||
# 官网 ↔ 答疑平台 联动方案(提案)
|
||||
|
||||
> 这份文档是**给 Website 仓库的改动提案**, 不涉及本仓库代码。
|
||||
> 平台侧的入口已经落地(见 `README.md` 「4.2 与课程官网联动」), 本文只讲官网侧怎么接。
|
||||
|
||||
## 0. 事实与现状(已核实)
|
||||
|
||||
| 项 | 事实 |
|
||||
| ---- | ---- |
|
||||
| 官网仓库 | `https://github.com/Tongji-High-level-Language-Programming/Website.git`(`/home/ymy/tjhlp-website`) |
|
||||
| 站点框架 | VitePress, `base: "/Website/"`, 构建命令 `pnpm docs:build` |
|
||||
| 线上地址 | `https://cpp.tongji.sh/Website/`(Apache `DocumentRoot=/home/httpd/hlp-website`, `RedirectMatch ^/$ /Website/`) |
|
||||
| 部署方式 | GitHub Actions: push 到 `main` → 构建 → 同时发 GitHub Pages 与该服务器(`rsync` 到 `/home/httpd/hlp-website/Website/`) |
|
||||
| 答疑平台 | `https://cpp.tongji.sh/QA/`(同一台机器, Apache `ProxyPass /QA`) |
|
||||
| 图片资产 | Git LFS(`.gitattributes`), 15 张 PR 截图都是 LFS 指针 |
|
||||
| 现状 main | 已到 PR #54; `#52` 的分支 `oierxjn:docs/gitea-tut` 落后 5 个提交, 但可干净合并 |
|
||||
|
||||
**关于 base 的坑(已实测)**: VitePress 会给 Markdown 里以 `/` 开头的站内链接自动加上
|
||||
`base`。部署产物里 `docs/ask-question/index.md` 的 `[本站 FAQ 页面](/faq/)` 生成的是
|
||||
`href="/Website/faq/"`。所以**跨站链接不能写 `/QA/`**(会被改写成 `/Website/QA/`),
|
||||
必须写完整 URL —— PR #52 里写完整 URL 是对的。
|
||||
|
||||
## 1. PR #52 现状
|
||||
|
||||
标题: *WIP: docs: Update Gitea tutorial and contact information with new references*(draft),
|
||||
作者 `oierxjn`, 分支 `docs/gitea-tut`, 18 个文件 `+167 -1`:
|
||||
|
||||
- `docs/faq/gitea/index.md` + 15 张截图: 平台使用指南(登录、搜索、创建/关闭 Issue)
|
||||
- `docs/.vitepress/config.mts`: 「常见问题」导航加下拉项「高程答疑平台」
|
||||
- `docs/ask-question/index.md`: 正文加入平台入口
|
||||
- `docs/contact.md`: 「QQ 群提问」→「答疑平台提问」
|
||||
|
||||
方向正确, 下面是可以补齐/修正的点。
|
||||
|
||||
## 2. 复查发现的问题
|
||||
|
||||
### P1 · 建议修掉
|
||||
|
||||
1. **`docs/faq/gitea/index.md` 没有文件末尾换行**(`\ No newline at end of file`)。
|
||||
仓库有 prettier + lint-staged, 建议补上, 避免后续 diff 噪音。
|
||||
2. **同页第一段主语写错**:「课程的答疑主要在…进行。**网站**仅限同济大学校园网或同济 VPN
|
||||
访问。」—— 上一句主语是平台。建议改为「平台与本站均仅限校园网 / 同济 VPN 访问」。
|
||||
3. **同页 `/contact.md` 链接**:`[联系团队](/contact.md)`。虽然 VitePress 能处理 `.md`
|
||||
链接, 但站内其他地方(导航、侧栏)统一写 `/contact`, 建议一致; 该句还缺句号。
|
||||
4. **旧组织名**:`docs/contact.md`(PR 改动行)与 `docs/.vitepress/config.mts` 的
|
||||
`socialLinks` 都写成 `Tongji-High-level-Programming-Language`(词序颠倒)。实测该
|
||||
地址目前 200 是因为 GitHub 的组织改名重定向, 建议改成当前组织名
|
||||
`Tongji-High-level-Language-Programming`, 不要依赖重定向。
|
||||
|
||||
### P2 · 建议调整
|
||||
|
||||
5. **入口层级偏低**:目前只有「常见问题」下拉里的一个子项。建议在**顶部导航**加一个
|
||||
一级「答疑平台」外链, 并在**首页 hero** 加一个 `答疑平台` 按钮 —— 这是学生最需要的入口。
|
||||
6. **首页提示过期**:`docs/index.md` 底部 `::: danger` 写着「所有通知、作业等重要信息请以
|
||||
官方课程 QQ 群为准」。既然答疑已迁到平台, 建议改为「以课程官网与答疑平台公告为准」,
|
||||
并把 `学会提问`/`FAQ` 之外补上平台入口。
|
||||
7. **`docs/faq/index.md` 没有平台入口**:FAQ 是学生最常翻的页面, 建议在顶部 tip 里直接
|
||||
给出平台链接与《使用指南》。
|
||||
8. **「为什么 Gitea 作为答疑平台?」整段引用了 Gitea 官方宣传文案**, 其中包含「极易安装…
|
||||
自建 Git 服务」这种推销语, 与网站正文风格不符。建议只保留后半段「如你所见, Gitea 提供了
|
||||
完整的 Issue 管理功能…」。
|
||||
9. **账号开通方式待确认**:同页写「账号目前由管理员统一开通, 没有额外的注册入口」。如果
|
||||
实际是统一身份认证(OIDC)首次登录自动建号, 这句会误导学生 —— 需要按实际流程改写。
|
||||
|
||||
### P3 · 后续
|
||||
|
||||
10. **截图会随定制上线而部分过期**:15 张截图拍摄于平台定制之前, 其中 `MainPage.png` 是
|
||||
Gitea 默认落地页(「一款极易搭建的自托管 Git 服务」), 定制上线后平台首页已换成答疑
|
||||
平台介绍; 若截图里出现过「工单」字样也与现在的 「Issue」不一致。建议定制上线后按同样
|
||||
流程重拍、**文件名不变**地替换, 这样正文不用改。
|
||||
11. **内容重复(已在平台侧处理完)**:官网提问指南与平台内的副本曾有重叠。2026-09 起
|
||||
**提问指南只在官网保留一份**(`/Website/qa/ask/`), 平台内的
|
||||
`/assets/tjhlp/ask-guide.html` 已删除, 平台页面与 Issue 模板的引导链接全部指向官网;
|
||||
官网页因此不必再考虑与平台副本同步的问题。
|
||||
|
||||
> **2026-09 官网改版后的路径**:提问指南 `/Website/qa/ask/`、常见问题 `/Website/qa/faq/`、
|
||||
> 联系我们 `/Website/contact.html`。旧的 `/Website/ask-question/`、`/Website/faq/` 已变成
|
||||
> 跳转页, `/Website/contact` 已经 404。本文下面几节写于改版前, 里面的
|
||||
> `/ask-question/`、`/contact.md` 等路径按新路径理解(PR #52 也要相应更新)。
|
||||
|
||||
## 3. 建议改动(可直接套用)
|
||||
|
||||
### 3.1 `docs/.vitepress/config.mts`
|
||||
|
||||
```ts
|
||||
// 答疑平台(校内 Apache 反代 /QA)。外链必须写完整 URL:
|
||||
// VitePress 会给以 / 开头的站内链接加上 base(/Website/), 写 /QA/ 会变成 /Website/QA/。
|
||||
const QA_URL = "https://cpp.tongji.sh/QA/";
|
||||
|
||||
// themeConfig.nav —— 在「首页」之后插入一级入口
|
||||
{ text: "答疑平台", link: QA_URL },
|
||||
|
||||
// 「常见问题」下拉保留(PR #52 已加)
|
||||
{
|
||||
text: "常见问题",
|
||||
link: "/faq/",
|
||||
items: [{ text: "答疑平台使用指南", link: "/faq/gitea/" }],
|
||||
},
|
||||
|
||||
// themeConfig.sidebar —— 「学会提问」之后加一条(侧栏支持外链)
|
||||
{ text: "答疑平台", link: QA_URL },
|
||||
|
||||
// socialLinks —— 顺手改成当前组织名
|
||||
link: "https://github.com/Tongji-High-level-Language-Programming/Website",
|
||||
```
|
||||
|
||||
### 3.2 `docs/index.md`
|
||||
|
||||
```yaml
|
||||
actions:
|
||||
- theme: brand
|
||||
text: 课程信息
|
||||
link: /syllabus/
|
||||
- theme: brand
|
||||
text: 答疑平台 # 新增
|
||||
link: https://cpp.tongji.sh/QA/
|
||||
- theme: alt
|
||||
text: 学会提问
|
||||
link: /ask-question/
|
||||
- theme: alt
|
||||
text: FAQ
|
||||
link: /faq/
|
||||
```
|
||||
|
||||
```md
|
||||
::: danger 注意
|
||||
|
||||
本网站目前仍处于试运行状态,可能存在内容的缺失、错误或更新不及时。所有通知、作业等重要信息
|
||||
请以课程官网与答疑平台的公告为准,课程群内也会同步。
|
||||
|
||||
:::
|
||||
```
|
||||
|
||||
### 3.3 `docs/faq/index.md`
|
||||
|
||||
```md
|
||||
::: tip
|
||||
|
||||
提问前请务必认真阅读 [学会提问](/ask-question/) 一文。课程答疑在
|
||||
[高程答疑平台](https://cpp.tongji.sh/QA/) 上进行,使用方式见 [答疑平台使用指南](/faq/gitea/)。
|
||||
|
||||
:::
|
||||
```
|
||||
|
||||
### 3.4 `docs/contact.md`
|
||||
|
||||
```md
|
||||
本校同学的课程相关问题,请在 [高程答疑平台](https://cpp.tongji.sh/QA/) 提问
|
||||
([使用指南](/faq/gitea/))
|
||||
|
||||
对本网站的意见与建议,可以直接提交
|
||||
[GitHub Issue](https://github.com/Tongji-High-level-Language-Programming/Website/issues)
|
||||
或者联系课程团队:
|
||||
```
|
||||
|
||||
### 3.5 `docs/faq/gitea/index.md`
|
||||
|
||||
- 第一段:「平台与本站均仅限同济大学校园网或同济 VPN 访问。」
|
||||
- `[联系团队](/contact.md)` → `[联系团队](/contact)`。
|
||||
- 文末补一个换行。
|
||||
- 「为什么 Gitea 作为答疑平台?」删掉官方宣传语的引用块, 保留后半段说明。
|
||||
- 如按 §3.1 在导航加了入口, 页内可直接用 `[答疑平台](https://cpp.tongji.sh/QA/)`。
|
||||
|
||||
## 4. 落地与验证
|
||||
|
||||
```bash
|
||||
cd ~/tjhlp-website
|
||||
git lfs install # 截图是 LFS 对象, 缺了会构建出坏图
|
||||
pnpm install
|
||||
pnpm docs:dev # 本地预览: http://localhost:5173/Website/
|
||||
pnpm docs:build # 站内死链会在构建期报错, 作为校验
|
||||
```
|
||||
|
||||
- PR #52 的分支落后 main 5 个提交(可干净合并), 建议 `git rebase origin/main` 后继续,
|
||||
或直接基于最新 main 重建分支; **截图是 LFS 对象, 不要用 patch 传递, 要用分支/PR 传**。
|
||||
- 合并到 `main` 后由 GitHub Actions 自动 rsync 到 `/home/httpd/hlp-website/Website/`,
|
||||
无需手工部署; 部署后可用 `curl -s https://cpp.tongji.sh/Website/ | grep 答疑平台` 抽查。
|
||||
- 平台侧的对应入口已就绪(导航栏「课程官网」、首页「相关站点」、Issue 模板
|
||||
`contact_links`), 两边合并后建议用 `customization/preview/preview.sh check` 复查。
|
||||
|
||||
## 5. 待确认
|
||||
|
||||
1. 平台对外地址长期是否就是 `https://cpp.tongji.sh/QA/`?若有域名计划, 建议官网只维护一个
|
||||
常量(如上面的 `QA_URL`)。
|
||||
2. 账号开通方式(管理员统一开通 / OIDC 首次登录自动注册)——决定 FAQ 里那句话怎么写。
|
||||
3. 「为什么 Gitea 作为答疑平台?」是保留精简版还是整段删除。
|
||||
4. 截图重拍的时间点(建议在平台定制部署上线后)。
|
||||
@@ -0,0 +1,118 @@
|
||||
# =============================================================================
|
||||
# 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 客制化: 首页 / 中文术语 / 去 Gitea 化)
|
||||
# 官方镜像里 GITEA_CUSTOM=/data/gitea, 因此定制内容是挂到
|
||||
# /data/gitea/{templates,public,options} —— 不是 /data/gitea/custom!
|
||||
# 这是仓库里的 customization/custom 目录, 相对路径按 deploy/ 解析。
|
||||
# 生效前先确保产物已生成: python3 customization/build.py
|
||||
# -----------------------------------------------------------------------------
|
||||
GITEA_CUSTOM_DIR=../customization/custom
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# 容器出站代理(见 compose.yaml 同段落注释 / README 陷阱 6)
|
||||
# 默认: compose.yaml 里显式写成空值, 即容器内【不用代理】。这不是省事, 是有意的:
|
||||
# * compose 会把「运行 compose 的 shell」里的 http_proxy 自动注入容器, 而本机登录
|
||||
# shell 里是 127.0.0.1:7890 —— 那个地址在容器里是容器自己, 一旦被注入, Gitea
|
||||
# 启动时 OIDC discovery 就失败, 统一身份认证登录 404; 显式给空值能挡住注入。
|
||||
# * 容器【直连外网是通的】(实测 dl.gitea.com / api.github.com / codeload 都能直连),
|
||||
# 平台功能相关的出站(OIDC)也在内网直连, 所以不需要代理。
|
||||
# 将来若确实要给容器配代理, 必须是【容器可达】的地址(别写 127.0.0.1, 那是容器自己):
|
||||
# -----------------------------------------------------------------------------
|
||||
#GITEA_HTTP_PROXY=https://cpp.tongji.sh:7890
|
||||
#GITEA_HTTPS_PROXY=https://cpp.tongji.sh:7890
|
||||
#GITEA_NO_PROXY=localhost,127.0.0.1,::1,10.80.42.185,.local,.internal
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# 版本(锁定, 便于回滚)
|
||||
# -----------------------------------------------------------------------------
|
||||
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
|
||||
+1007
File diff suppressed because it is too large
Load Diff
+603
@@ -0,0 +1,603 @@
|
||||
# CI/CD:main 自动部署(Gitea Actions 方案)
|
||||
|
||||
> **状态:已落地并本地验证通过(2026-09-13),只差一次 `git push`。**
|
||||
> runner 已注册、部署克隆已建、生产已切到部署克隆、整条部署路径(含真实 job 容器)
|
||||
> 已在本机预演通过;推送 `main` 后第一次 CI 运行即接管。**全程不需要 root。**
|
||||
>
|
||||
> 本文标注 **[实测]** 的结论都是 2026-09-13 在本机跑出来的,命令写在对应位置,可复现。
|
||||
> 当前进度与剩余动作见 §0.1。
|
||||
> 相关文档:[deploy/README.md](README.md)(部署与陷阱,含本次踩到的 3 个坑)、
|
||||
> [customization/README.md](../customization/README.md)(定制机制与预览)。
|
||||
|
||||
---
|
||||
|
||||
## 0. 目标
|
||||
|
||||
`course-team/tjhlp-gitea` 的 `main` 一有推送,就自动把平台更新到那个提交:
|
||||
构建定制产物 → 重建容器 → 跑验证 → 失败自动回滚。人工只负责 review 和 push。
|
||||
|
||||
不在本方案范围内:Gitea 版本升级(要备份 + 数据库迁移,仍走 [README §7](README.md) 人工流程)、
|
||||
`issue-templates` 重新推送(运营操作)、官网仓库(`Website`)的部署(那是 GitHub Actions 的事)。
|
||||
|
||||
### 0.1 落地现状与剩余动作(更新到 2026-09-22)
|
||||
|
||||
**CI/CD 已上线跑通。** `action_run` 表里共 5 次运行:前几次是打通路上的跳过/失败,最新一次
|
||||
(HEAD `9954700`)`status=1`(=Success),`deploy/.state/last-deployed` = `9954700` —— 生产
|
||||
就是 CI 部署的版本。
|
||||
|
||||
| 项 | 证据 |
|
||||
|---|---|
|
||||
| 部署克隆 `/home/ymy/deploy/tjhlp-gitea`(`origin` = 本机裸仓库,免凭据) | `git remote -v`;`deploy/.env` 600 |
|
||||
| runner 已注册 | `action_runner`:`tjhlp-gitea-1 / v0.6.1 / ["self-hosted"]` |
|
||||
| 生产由 CI 部署 | `last-deployed` = HEAD 的 SHA;`action_run` 最新一次 `status=1` |
|
||||
| job 容器里工具齐全 | `act_runner exec` 预演:`Python 3.10.12 / git 2.55 / docker server 29.8.0 / compose v5.5.1` |
|
||||
|
||||
2026-09-21 打通时踩的三个坑(对应当天几次红色的运行):
|
||||
|
||||
1. **`container.valid_volumes` 为空表时,挂载会被静默丢弃**(只打一行
|
||||
`... is not a valid volume, will be ignored`)→ job 容器里没有部署克隆,第一步
|
||||
`cd /home/ymy/deploy/tjhlp-gitea` 就失败。修法:把要挂的路径列进白名单。
|
||||
2. **部署克隆的 `origin` 是宿主上的本地裸库**(`/srv/gitea/...`),job 容器里没有它 →
|
||||
`git fetch` 报 "does not appear to be a git repository"。修法:把 `/srv/gitea` 只读挂进去。
|
||||
3. **workflow 的 step 之间不共享工作目录**,第二步要自己 `cd` 过去(`actions/checkout` 那种
|
||||
"代码在当前目录"的心智模型在这里不成立)。
|
||||
|
||||
2026-09-22 本轮改动:**把宿主能力从"runner 全局发给每个 job"收窄成"deploy job 自己申报"**:
|
||||
|
||||
- `container.docker_host: "-"` → 不再自动把 docker socket 挂进 job 容器;
|
||||
- 删掉 `container.options` 里的全局挂载;
|
||||
- 五项挂载(部署克隆、`/srv/gitea`、socket、docker CLI、compose 插件)改为在
|
||||
`.gitea/workflows/deploy.yml` 的 `container.volumes` 里申报,并全部列进
|
||||
`container.valid_volumes` 白名单。
|
||||
|
||||
效果:**将来加的 PR 检查/测试 job 默认是裸容器**——没有宿主路径,也申报不了白名单之外的卷
|
||||
(本机实测:不申报任何挂载的 job 看不到 `/home/ymy/deploy` 与 `/srv/gitea`)。socket 那一项
|
||||
在真实调度路径上的确认方式与失败模式见 §9,其余残留见 §7.2。
|
||||
|
||||
剩余动作:
|
||||
|
||||
1. 本轮改动**要等一次 push 才能端到端验证**(判据与回退方式见 §9 第 2 条)。
|
||||
2. 用一个测试 fork 发 PR,确认 fork PR 的 workflow 审批行为(§9);确认前不要把仓库
|
||||
开放给不可信贡献者。
|
||||
3. 给 `main` 加分支保护(§4.4)。
|
||||
|
||||
---
|
||||
|
||||
## 1. 现状与约束 **[实测]**
|
||||
|
||||
| 项 | 实测值 | 对方案的影响 |
|
||||
|---|---|---|
|
||||
| Gitea | 1.27.3;Actions 默认开启(`modules/setting/actions.go` 里 `Enabled: true`),仓库页有 `/actions` | 不用改配置就能用 |
|
||||
| 已注册 runner | 方案制定时**无**(现已注册,见 §0.1) | 要自己起一个 |
|
||||
| `act_runner` 镜像 | `docker pull gitea/act_runner:latest` 成功:**arm64, v0.6.1, 69.3MB** | runner 用容器跑,**不需要 root** |
|
||||
| job 镜像 | `docker.gitea.com/runner-images:ubuntu-22.04`(Gitea 官方, arm64 可用)、`catthehacker/ubuntu:act-22.04`(arm64, 压缩约 512MB)、`node:20-bookworm-slim`、`rockylinux:8` 的 manifest 都能取到 | 有现成镜像可跑容器模式 job |
|
||||
| 宿主出网 | 国内直连 `200`;境外经代理 `200`(`https://dl.gitea.com/...`、`https://github.com` 经 `127.0.0.1:7890` 均 `200`) | 正常联网,不是离线环境 |
|
||||
| 容器出网 | 容器内直连:`dl.gitea.com` `200`、`api.github.com` `200`、`codeload.github.com` `301`;**`github.com` 主站直连 12s 超时** | `uses: actions/checkout` 这类动作走 codeload/api 通常可以;主站要通就得给镜像或 `github_mirror` |
|
||||
| docker daemon 代理 | `/etc/systemd/system/docker.service.d/http-proxy.conf` 里 `HTTP(S)_PROXY=http://127.0.0.1:7890` | 镜像拉取走代理,正常 |
|
||||
| `ymy` 的组 | `ymy, wheel, git(982), docker(980)` | 容器方案不需要 sudo;host 模式才需要 |
|
||||
| 裸仓库 | `/srv/gitea/git/repositories/course-team/tjhlp-gitea.git`,`drwxr-xr-x git:git`,`git ls-remote` 通(需 `safe.directory`,见 §4.1) | CI 可以**免凭据**取代码 |
|
||||
| 现成积木 | `deploy/scripts/{verify,backup,restore}.sh`、`customization/build.py`、`preview.sh check` | 直接复用 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 方案总览
|
||||
|
||||
### 2.1 架构
|
||||
|
||||
```text
|
||||
开发者 push main
|
||||
│
|
||||
▼
|
||||
Gitea (10.80.42.185/QA) ── 调度 workflow ──► act_runner(docker compose 服务, 容器)
|
||||
▲ │ 拉起 job 容器
|
||||
│ 日志/状态显示在仓库 Actions 标签 ▼
|
||||
└──────────────────── job 容器(network: host;宿主能力由 job 自己申报)
|
||||
├─ 挂 docker.sock → 可执行 docker compose
|
||||
├─ 挂 /home/ymy/deploy(同路径, 部署克隆)+ /srv/gitea(ro, 它的 origin)
|
||||
└─ 跑 auto-deploy.sh: build.py → up -d → verify → 失败回滚
|
||||
未申报的 job(将来的 PR 检查)拿不到上面任何一项
|
||||
|
||||
### 2.2 runner 形态:容器(推荐)vs 宿主二进制
|
||||
|
||||
| | **A. 容器(推荐)** | B. 宿主二进制 + host 模式 |
|
||||
|---|---|---|
|
||||
| 安装 | `docker compose up -d`(镜像实测可拉) | 下载二进制 + **需要 sudo** 装 systemd 单元 |
|
||||
| job 执行 | job 容器(镜像由 label 决定) | 直接在宿主以 `ymy` 执行 |
|
||||
| 工具依赖 | 靠 job 镜像(要确认镜像里有 git/python3/docker CLI) | 宿主现成,最省事 |
|
||||
| 挂载 | 由 deploy job 在 `container.volumes` 里申报(受 runner 的 `valid_volumes` 白名单约束) | 无 |
|
||||
| 开机自启 | compose 的 `restart: unless-stopped` | systemd |
|
||||
| 结论 | **默认选它**:不需要 root、标准、日志清晰 | 想少一层容器、且你愿意跑一次 sudo 时选它 |
|
||||
|
||||
act_runner v0.6.1 自己的 `generate-config` 输出里明确写了两种 label 写法,两个事实由此确认:
|
||||
|
||||
```text
|
||||
# Like: "macos-arm64:host" or "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
|
||||
labels:
|
||||
- "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
|
||||
container:
|
||||
# Could be host, bridge or the name of a custom network.
|
||||
network: ""
|
||||
```
|
||||
|
||||
即 **`:host` 支持**(备选 B 可用)、**`container.network: host` 支持**(方案 A 里让 job 容器
|
||||
能和宿主共用回环,`verify.sh` 里 `127.0.0.1:2080` 的检查才继续有效)。
|
||||
|
||||
### 2.3 触发与门禁
|
||||
|
||||
- 触发:`push` 到 `main`,外加 `workflow_dispatch`(落地初期先只手动触发);
|
||||
- 跳过:提交信息含 `[skip deploy]` 不部署(与 Gitea 自带的 `[skip ci]` 同风格);
|
||||
- 串行:workflow 的 `concurrency` + 脚本里的 `flock` 双保险;
|
||||
- 只认 `main`:job 级 `if` 卡死分支,PR/其它分支即使跑工作流也不碰生产。
|
||||
|
||||
---
|
||||
|
||||
## 3. 组件清单
|
||||
|
||||
| 组件 | 位置 | 谁维护 |
|
||||
|---|---|---|
|
||||
| 部署克隆 | `/home/ymy/deploy/tjhlp-gitea` | 本方案新建(§4.1) |
|
||||
| 部署凭据 | `deploy/.env`(`chmod 600`,已 gitignore) | 从现有部署复制 |
|
||||
| 部署状态 | `deploy/.state/last-deployed`(上次成功的 SHA) | 脚本写,加进 `.gitignore` |
|
||||
| runner | `deploy/runner/compose.yaml` + `deploy/runner/config.yaml` + `deploy/runner/data/`(gitignore) | 新增到仓库 |
|
||||
| 工作流 | `.gitea/workflows/deploy.yml` | 新增到仓库(§5.1) |
|
||||
| 部署脚本 | `deploy/scripts/auto-deploy.sh` | 新增到仓库(§5.2) |
|
||||
| 定制断言 | `customization/check.sh <base-url>` | 新增到仓库(§5.3) |
|
||||
|
||||
---
|
||||
|
||||
## 4. 落地步骤
|
||||
|
||||
### 4.1 部署克隆(不需要 root)
|
||||
|
||||
```bash
|
||||
# 让 ymy 能读 Gitea 的裸仓库。
|
||||
# ★ 实测: git -c safe.directory=... 对本机 git 无效, 必须写进配置文件才生效。
|
||||
git config --global --add safe.directory \
|
||||
/srv/gitea/git/repositories/course-team/tjhlp-gitea.git
|
||||
|
||||
# 从裸仓库克隆: origin 就指向本机裸仓库, CI 全程不需要任何 git token
|
||||
git clone /srv/gitea/git/repositories/course-team/tjhlp-gitea.git \
|
||||
/home/ymy/deploy/tjhlp-gitea
|
||||
|
||||
cd /home/ymy/deploy/tjhlp-gitea
|
||||
cp /home/ymy/tjhlp-gitea/deploy/.env deploy/.env # 部署密钥, 别提交
|
||||
chmod 600 deploy/.env
|
||||
mkdir -p deploy/.state
|
||||
```
|
||||
|
||||
> ⚠️ 从此 `deploy/.env` 有**两份**(dev 克隆一份、部署克隆一份)。约定:**部署克隆那份是权威**,
|
||||
> dev 克隆那份只服务本地预览;改密钥时两边同步。
|
||||
>
|
||||
> ⚠️ 切换后**不要再从 dev 克隆 `up -d`**:compose 项目名同为 `gitea`(同一组容器),但 bind mount
|
||||
> 的源路径按 compose 文件所在目录解析,两边会互相覆盖。dev 克隆只留开发与预览。
|
||||
|
||||
### 4.2 起 runner 并注册(不需要 root)
|
||||
|
||||
先在 Gitea 上拿一个**仓库级**注册令牌(API 实测存在:
|
||||
`POST /api/v1/repos/{owner}/{repo}/actions/runners/registration-token`;
|
||||
也可以在 仓库 → Settings → Actions → Runners 页面点按钮):
|
||||
|
||||
```bash
|
||||
curl -sS -X POST \
|
||||
-H "Authorization: token <你的 PAT, 需要 repo 权限>" \
|
||||
"https://cpp.tongji.sh/QA/api/v1/repos/course-team/tjhlp-gitea/actions/runners/registration-token" \
|
||||
| python3 -c 'import json,sys; print(json.load(sys.stdin)["token"])'
|
||||
```
|
||||
|
||||
把令牌写进 `deploy/runner/.env`(gitignore),然后:
|
||||
|
||||
```bash
|
||||
cd /home/ymy/deploy/tjhlp-gitea/deploy/runner
|
||||
docker compose up -d
|
||||
docker compose logs -f runner # 看到 "runner registered successfully" 即可
|
||||
```
|
||||
|
||||
仓库 → Settings → Actions → Runners 里应出现 `tjhlp-gitea-1`(Idle)。注册令牌用完即弃:
|
||||
注册结果存在 `deploy/runner/data/.runner`,之后 runner 用它通信,不会过期。
|
||||
|
||||
`deploy/runner/compose.yaml`:
|
||||
|
||||
```yaml
|
||||
name: gitea-runner
|
||||
services:
|
||||
runner:
|
||||
image: gitea/act_runner:latest # 实测 arm64 / v0.6.1 / 可拉取
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
# 这组变量名来自镜像里的 /usr/local/bin/run.sh(实测)
|
||||
GITEA_INSTANCE_URL: https://cpp.tongji.sh/QA
|
||||
GITEA_RUNNER_REGISTRATION_TOKEN: ${RUNNER_REGISTRATION_TOKEN:?先按 §4.2 拿令牌}
|
||||
GITEA_RUNNER_NAME: tjhlp-gitea-1
|
||||
# 不要在 env 里设 GITEA_RUNNER_LABELS: act_runner 会警告
|
||||
# "Labels from command will be ignored, use labels defined in config file.",
|
||||
# label 以 config.yaml 为准(实测)
|
||||
CONFIG_FILE: /config/config.yaml
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock # runner 用它拉起 job 容器
|
||||
- ./data:/data # 注册凭据 (.runner)
|
||||
- ./config.yaml:/config/config.yaml:ro
|
||||
```
|
||||
|
||||
`deploy/runner/config.yaml`:
|
||||
|
||||
```yaml
|
||||
log:
|
||||
level: info
|
||||
runner:
|
||||
file: /data/.runner
|
||||
capacity: 1 # 部署必须串行, 一个 job 一个 job 地跑
|
||||
timeout: 30m
|
||||
labels:
|
||||
# job 跑在容器里; 镜像换成本地已有/更小的亦可(如 catthehacker/ubuntu:act-22.04)
|
||||
- "self-hosted:docker://docker.gitea.com/runner-images:ubuntu-22.04"
|
||||
container:
|
||||
network: host # job 容器与宿主共用网络: 127.0.0.1:2080 与 10.80.42.185 都能直连
|
||||
docker_host: "-" # 自动找 daemon, 但【不】把 socket 挂进 job 容器(要用 docker 的 job 自己申报)
|
||||
valid_volumes: # 允许 job 申报的挂载白名单(glob 匹配挂载源路径; [] = 一个都不许)
|
||||
- /home/ymy/deploy
|
||||
- /srv/gitea
|
||||
- /var/run/docker.sock
|
||||
- /usr/bin/docker
|
||||
- /usr/libexec/docker/cli-plugins
|
||||
# 这里【故意不写】全局 options: 挂载由 deploy job 自己申报, 见 §5.1
|
||||
force_pull: false # 镜像已有就别每次拉
|
||||
cache:
|
||||
enabled: true
|
||||
```
|
||||
|
||||
四处关键点:
|
||||
|
||||
- **白名单管两头**:job 申报的 `container.volumes` 和全局 `options` 里的 `--volume` 都要在
|
||||
`valid_volumes` 里,否则被**静默丢弃**(`... is not a valid volume, will be ignored`),
|
||||
2026-09-21 实际因此失败;
|
||||
- **同路径挂载 `/home/ymy/deploy`**:`docker compose` 在 job 容器里把相对挂载解析成绝对路径后
|
||||
交给宿主 daemon 执行,路径不一致会挂到空目录;
|
||||
- **`/srv/gitea` 只读**:部署克隆的 `origin` 是这个宿主路径下的裸库,job 容器里没有它就
|
||||
`git fetch` 不了(2026-09-21 实际踩到);
|
||||
- **不把 `docker.sock` 写进全局 `options`**:那等于每个 job 都拿到 root。改由 deploy job
|
||||
自己申报,而 `docker_host: "-"` 保证它不会和"自动挂载"撞成
|
||||
`Duplicate mount point: /var/run/docker.sock`。
|
||||
|
||||
### 4.3 试运行(手动触发)
|
||||
|
||||
1. 提交 §5 的文件,workflow 的 `on:` **先只留 `workflow_dispatch`**(没有 runner 时 push 触发
|
||||
会一直挂在"等待 runner");
|
||||
2. 仓库 → Actions → deploy → **Run workflow**(选 `main`);
|
||||
3. 盯日志确认:构建 → `up -d` → 验证全过 → Actions 绿色;
|
||||
4. 故意推一个坏提交(例如把 `overrides/locale_zh-CN.json` 的键写错)验证**回滚路径**真的生效。
|
||||
|
||||
### 4.4 打开自动触发 + 加保护
|
||||
|
||||
1. 把 `push: branches: [main]` 加回 workflow;
|
||||
2. 仓库 → Settings → Branches → 给 `main` 加保护:**要求 PR + 至少 1 个 review**;
|
||||
3. `deploy/README.md` 的快速索引里已有一行指向本文档。
|
||||
|
||||
---
|
||||
|
||||
## 5. 流水线内容
|
||||
|
||||
### 5.1 `.gitea/workflows/deploy.yml`
|
||||
|
||||
刻意做得很薄:workflow 只做"同步到目标提交 + 调仓库里的部署脚本",逻辑都在
|
||||
`auto-deploy.sh`(可版本化、可手工跑、可本地调试)。
|
||||
|
||||
```yaml
|
||||
# main 推送后自动部署到 10.80.42.185/QA。
|
||||
# 逻辑都在 deploy/scripts/auto-deploy.sh 里, 这里只负责"同步到目标提交 + 调脚本"。
|
||||
# 详见 deploy/ci-cd.md。
|
||||
name: deploy
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
workflow_dispatch:
|
||||
|
||||
concurrency:
|
||||
group: deploy-main
|
||||
cancel-in-progress: false
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
# 只认 main 的 push 或手动触发; 提交信息含 [skip deploy] 则跳过
|
||||
if: >-
|
||||
github.event_name == 'workflow_dispatch' ||
|
||||
(github.ref == 'refs/heads/main' &&
|
||||
!contains(github.event.head_commit.message, '[skip deploy]'))
|
||||
runs-on: self-hosted
|
||||
timeout-minutes: 30
|
||||
# ★ 宿主能力(docker socket、部署克隆、裸库、docker CLI)由【本 job】申报,而不是由
|
||||
# runner 全局发给每个 job。runner 侧的 container.valid_volumes 是允许清单:
|
||||
# 没列进去的挂载会被丢弃,所以这里的每一项都要在 deploy/runner/config.yaml 里有对应项。
|
||||
# 将来加 PR 检查/测试 workflow 时,那个 job 不申报就什么都拿不到(无 socket = 无 root)。
|
||||
container:
|
||||
volumes:
|
||||
- /home/ymy/deploy:/home/ymy/deploy # 工作目录(auto-deploy.sh 要写 .state)
|
||||
- /srv/gitea:/srv/gitea:ro # deploy 克隆的 origin(本地裸库)
|
||||
- /var/run/docker.sock:/var/run/docker.sock # docker compose up -d
|
||||
- /usr/bin/docker:/usr/bin/docker:ro # 宿主 docker CLI
|
||||
- /usr/libexec/docker/cli-plugins:/usr/libexec/docker/cli-plugins:ro # compose 插件
|
||||
steps:
|
||||
- name: 同步到目标提交
|
||||
run: |
|
||||
set -euo pipefail
|
||||
cd /home/ymy/deploy/tjhlp-gitea
|
||||
git fetch --prune origin
|
||||
# -f: 部署克隆是 CI 独占的; 上一个已部署版本的 deploy/runner/* 等文件在本版本
|
||||
# 若已被跟踪, 会作为"未跟踪文件"挡住普通 checkout(实测)
|
||||
git checkout -f --detach "${{ github.sha }}"
|
||||
git --no-pager log --oneline -1
|
||||
- name: 构建并部署(失败自动回滚)
|
||||
run: |
|
||||
set -euo pipefail
|
||||
# 工作流没有 actions/checkout, 默认工作目录里没有代码; 上一步已把
|
||||
# 部署克隆同步到目标提交, 这里必须显式 cd 过去 (2026-09-21 实际踩到)。
|
||||
cd /home/ymy/deploy/tjhlp-gitea
|
||||
./deploy/scripts/auto-deploy.sh
|
||||
```
|
||||
|
||||
`container.volumes` 那一块是 2026-09-22 收窄授权的结果:需要宿主能力的只有这一个 job,
|
||||
所以挂载在它这里申报;runner 侧的 `valid_volumes` 决定哪些申报能被接受。**加新的 workflow
|
||||
(例如 PR 检查)时不需要、也不要给它申报这些卷** —— 它默认就是裸容器。
|
||||
|
||||
**不写 `uses:`** 的理由:本项目不需要——代码从本机裸仓库取、部署逻辑是仓库里的脚本,
|
||||
省掉每次运行下载 action 的开销,也避开 `github.com` 主站直连超时带来的不确定性。
|
||||
将来若要做 PR 检查(lint/pytest)想用现成 action,两条路:给 runner 容器配容器可达的代理,
|
||||
或在 runner 的 `config.yaml` 里设置 `github_mirror`(v0.6.1 的配置注释里就是为"特殊网络环境"
|
||||
准备的),把 `uses:` 的 github 地址替换成镜像。
|
||||
|
||||
### 5.2 `deploy/scripts/auto-deploy.sh`
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# main 自动部署。由 .gitea/workflows/deploy.yml 调用, 也可手工执行:
|
||||
# ./auto-deploy.sh # 部署当前 checkout
|
||||
# ./auto-deploy.sh <sha> # 部署指定提交
|
||||
set -euo pipefail
|
||||
|
||||
REPO_DIR=$(cd "$(dirname "$0")/../.." && pwd)
|
||||
STATE_DIR="${REPO_DIR}/deploy/.state"
|
||||
STATE_FILE="${STATE_DIR}/last-deployed"
|
||||
PUBLIC_URL="${GITEA_PUBLIC_URL:-http://10.80.42.185/QA}"
|
||||
|
||||
# 本机回环验证不能走代理, 否则会拿 502 冒充故障(见 README 陷阱 5)
|
||||
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY
|
||||
export no_proxy='*' NO_PROXY='*'
|
||||
# 既能在 job 容器里跑, 也能在宿主上跑: 脚本用 pick_python() 自己挑一个 ≥3.7 的解释器
|
||||
# (宿主 /usr/bin/python3 是 3.6, 见 README 陷阱 9), 不要写死某台机器的 pyenv 路径
|
||||
|
||||
mkdir -p "$STATE_DIR"
|
||||
TARGET=${1:-$(git -C "$REPO_DIR" rev-parse HEAD)}
|
||||
PREV=$(cat "$STATE_FILE" 2>/dev/null || true)
|
||||
HASH_FILE="${STATE_DIR}/custom-hash" # 上次成功部署时 custom/ 的指纹
|
||||
|
||||
exec 9>"${STATE_DIR}/lock" # workflow 的 concurrency 之外再加一道
|
||||
flock -n 9 || { echo "[auto-deploy] 已有部署在跑, 退出"; exit 0; }
|
||||
|
||||
echo "[auto-deploy] 目标 ${TARGET} (上次成功: ${PREV:-无})"
|
||||
cd "$REPO_DIR"
|
||||
|
||||
# customization/custom/ 的指纹: 模板、静态页、生成的语言文件都在里面, 都是启动时加载的
|
||||
custom_hash() {
|
||||
(cd customization/custom && find . -type f -exec sha256sum {} + | sort | sha256sum | cut -d' ' -f1)
|
||||
}
|
||||
|
||||
deploy() { # deploy force = 无条件重启(回滚路径用)
|
||||
python3 customization/build.py # 生成语言文件 + 规范 custom/ 权限(容器用户要能读)
|
||||
python3 customization/build.py --check # 生成物/权限校验, 不过就中止, 不碰容器
|
||||
( cd deploy && docker compose up -d ) # 幂等: 只有配置/镜像变化时才重建
|
||||
# ★ 必须和【上次成功部署的指纹】比, 不能只比 build.py 前后 —— 后者只能发现语言
|
||||
# 文件变化, 纯模板改动前后一模一样, 于是永远不重启、容器继续用旧模板(详见下方说明)
|
||||
if [[ -n "${1:-}" || $(custom_hash) != "$(cat "$HASH_FILE" 2>/dev/null)" ]]; then
|
||||
( cd deploy && docker compose restart gitea )
|
||||
fi
|
||||
}
|
||||
|
||||
verify() {
|
||||
( cd deploy && ./scripts/verify.sh ) # 容器健康 + 本机 API + 经 Apache 反代
|
||||
customization/check.sh "$PUBLIC_URL" # 定制断言: 首页/登录页/OIDC/术语(见 5.3)
|
||||
}
|
||||
|
||||
rollback() {
|
||||
[[ -z "${PREV}" ]] && { echo "[auto-deploy] 无历史版本可回退, 保持现状"; return 0; }
|
||||
echo "[auto-deploy] 回滚到 ${PREV}"
|
||||
git checkout --detach "$PREV"
|
||||
deploy force || true # 强制重启: 失败那次可能已用新模板重启过容器
|
||||
verify || true
|
||||
}
|
||||
|
||||
if deploy && verify; then
|
||||
echo "$TARGET" > "$STATE_FILE"
|
||||
custom_hash > "$HASH_FILE" # 记下这次成功部署的指纹, 供下次比较
|
||||
echo "[auto-deploy] ✅ 部署成功 ${TARGET}"
|
||||
else
|
||||
echo "[auto-deploy] ❌ 部署或验证失败, 开始回滚"
|
||||
rollback
|
||||
exit 1 # 让这次 Actions 运行标红, 完整日志留在 UI 里
|
||||
fi
|
||||
```
|
||||
|
||||
> **为什么非要 `restart`(2026-09-22 踩到的坑)**:模板与语言文件是 Gitea **启动时**加载的,
|
||||
> 而 `docker compose up -d` 在 compose 配置没变时**不会重建容器**。最早的实现比较的是
|
||||
> `build.py` 运行前后的指纹——那只会在语言文件被重新生成时才变;**纯模板改动**(改文案、
|
||||
> 换链接)前后完全一样,于是从不重启,容器继续用旧模板,`check.sh` 断言失败 → 整个部署
|
||||
> 被判失败并回滚(「提问指南」换地址那个提交就是这样被回滚的)。改成把指纹记在
|
||||
> `.state/custom-hash` 里、与**上次成功部署**比较后,模板改动会触发重启。
|
||||
>
|
||||
> `restart` 还顺带修一个 bind mount 的坑:挂载**源目录**被「删掉再建」(例如某个提交把
|
||||
> `custom/public/` 下的文件删光了,git 顺手删掉空目录)后,容器里挂的仍是**旧 inode**,
|
||||
> 看到的是一个空目录——只有重新 start 才会解析到新目录。同一次事故里线上的
|
||||
> `/QA/assets/tjhlp/ask-guide.html` 就是这么变成 404 的(已在预览上复现并验证 restart 能修)。
|
||||
> CI 若只更新了文档/脚本(`custom/` 没动),指纹相同则不重启,省掉一次无谓的停机。
|
||||
|
||||
落库前的两个小动作:`.gitignore` 加 `deploy/.state/`、`deploy/runner/data/`、
|
||||
`deploy/runner/.env`;给 `auto-deploy.sh` 加可执行位(`git` 只记可执行位)。
|
||||
|
||||
**不做**的事及理由:
|
||||
|
||||
- 每次部署不做数据库备份:部署只改代码/配置,DB 不动;且 `deploy/backups/` 是 `root:root`,
|
||||
CI 以 `ymy` 跑写不进去。版本升级仍走 README §7(带备份);
|
||||
- 不自动重推 `issue-templates`:运营动作,不该跟代码推送耦合。
|
||||
|
||||
### 5.3 新增 `customization/check.sh <base-url>`
|
||||
|
||||
`preview.sh check` 里那一串"定制有没有生效"的断言(首页文案、页脚、meta、静态页、官网链接、
|
||||
不出现「工单」、登录页两张卡、无通行密钥方框)正是部署后要守的东西。落地时把它抽出来共用:
|
||||
|
||||
```bash
|
||||
customization/check.sh http://127.0.0.1:2081 # 预览
|
||||
customization/check.sh https://cpp.tongji.sh/QA # 生产(CI 里调)
|
||||
```
|
||||
|
||||
生产侧再加两条(今天踩过的坑,必须自动化守住):
|
||||
|
||||
```bash
|
||||
# 1) OIDC 认证源注册成功: 必须是 307 跳到统一身份认证; 404 = 认证源没注册上
|
||||
curl -sS --noproxy '*' -o /dev/null -w '%{http_code} %{redirect_url}\n' \
|
||||
"${BASE}/user/oauth2/%E9%AB%98%E7%A8%8B%E7%BB%9F%E4%B8%80%E8%BA%AB%E4%BB%BD%E8%AE%A4%E8%AF%81"
|
||||
# 2) 登录页有「管理员登录」卡片且没有 passkey 空方框
|
||||
curl -sS --noproxy '*' -H 'Accept-Language: zh-CN' "${BASE}/user/login" | grep -c '管理员登录'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 失败与回滚
|
||||
|
||||
| 失败点 | 行为 |
|
||||
|---|---|
|
||||
| `build.py` 报错(overrides 键不存在/占位符改坏/文件不可读) | 立即中止,**不碰容器**,Actions 标红 |
|
||||
| `docker compose up -d` 失败(配置语法/镜像缺失) | 重试无意义 → 直接回滚 |
|
||||
| 容器起不来(模板报错、权限 600 之类的 `[F]`) | `verify.sh` 等到 start_period 结束仍非 healthy → 回滚 |
|
||||
| 验证断言失败(首页文案丢了、OIDC 404、出现「工单」) | 回滚 |
|
||||
| 回滚也失败 | 脚本打印现场并 `exit 1`;线上仍是坏版本,需要人工介入(`docker compose logs`) |
|
||||
| runner 掉线 | 推送后 Actions 显示"等待 runner",**不会**部署、也不影响线上;`docker compose up -d` 恢复 |
|
||||
|
||||
回滚 = `git checkout --detach <上一个成功 SHA>` + 重新 `up -d`,只动代码与挂载文件;
|
||||
数据库、`/srv/gitea` 数据、`.env` 全程不参与,所以几十秒内完成。
|
||||
|
||||
---
|
||||
|
||||
## 7. 安全
|
||||
|
||||
### 7.1 收窄后的边界(2026-09-22 起)
|
||||
|
||||
runner 不再把宿主能力全局发给每个 job:
|
||||
|
||||
- `container.docker_host: "-"`:**不**把 docker socket 自动挂进 job 容器;
|
||||
- 需要宿主能力的是 **deploy job 自己**,它在 `container.volumes` 里申报五项挂载;
|
||||
- `container.valid_volumes` 是允许清单:申报了但不在表里的卷会被**丢弃**(不是报错),
|
||||
所以这个 runner 上的任何 job 都挂不上 `/`、`/etc`、`~/.ssh` 之类。
|
||||
|
||||
也就是说,"能 root 宿主"从"这个 runner 上的**所有** job"收窄成了"**deploy job** 加上白名单
|
||||
里那五项"。将来加 PR 检查/测试 workflow 时,那些 job 默认是裸容器(实测:不申报任何挂载的
|
||||
job 看不到 `/home/ymy/deploy`、`/srv/gitea`)。
|
||||
|
||||
### 7.2 仍然存在的残留(别当成"已经隔离了")
|
||||
|
||||
1. **能 push workflow 的人 = 能 root 宿主。** job 容器里跑的是仓库里的脚本,而 deploy job
|
||||
必须有 socket;`main` 的分支保护才是这条的实际控制点。
|
||||
⚠️ 另外 v0.6.1 **不会**剥离 job 自己申报的逃逸类 `container.options`(如 `--privileged`):
|
||||
这是 runner 3.x 才有的行为(3.x 文档写明"会剥离并告警",v0.6.1 的 `generate-config` 里
|
||||
没有这类说明)。所以**升级 runner 到 3.x 值得排期**——镜像 `gitea/runner:3` 已经存在,
|
||||
配置键(`valid_volumes`/`docker_host`/`container.network`)也是同一套。
|
||||
2. **`container.network: host` 是 runner 级设置**,收窄不到单个 job:这个 runner 上的每个
|
||||
job 都共享宿主网络,因此能访问宿主回环上的服务(例如 `127.0.0.1:2080` 的 Gitea)。
|
||||
要收窄它,得把 `--network host` 挪到 deploy job 的 `container.options`,并把 `verify.sh`
|
||||
的回环检查改成"连不上就跳过、只认公网 URL"——留作后续。
|
||||
3. **fork PR 的策略仍未确认**(§9):若 fork PR 能不经批准直接跑 workflow,等于把宿主 root
|
||||
交给外部 PR;确认之前不要把仓库开放给不可信贡献者。
|
||||
4. `[skip deploy]`、`if:` 是防误操作,不是安全边界。
|
||||
|
||||
### 7.3 其余
|
||||
|
||||
- runner 只注册成**仓库级**(`/repos/{owner}/{repo}/actions/runners/registration-token`),
|
||||
不要注册成 instance/org 级——否则组织里任何仓库都能用这个 runner 拿到宿主 root。
|
||||
- 凭据最小化:部署流程**不需要任何 git token**(从本机裸仓库 fetch);注册令牌一次性用完即弃。
|
||||
- `gitea/act_runner` 镜像来自 Docker Hub 官方组织仓库;落地时记录 tag/digest(升级方式同 README)。
|
||||
|
||||
---
|
||||
|
||||
## 8. 日常操作
|
||||
|
||||
```bash
|
||||
# 手动部署当前 main(不依赖 Actions/runner)
|
||||
/home/ymy/deploy/tjhlp-gitea/deploy/scripts/auto-deploy.sh
|
||||
|
||||
# 回滚到指定提交
|
||||
cd /home/ymy/deploy/tjhlp-gitea && git checkout --detach <sha> && ./deploy/scripts/auto-deploy.sh
|
||||
|
||||
# runner 启停 / 看日志
|
||||
cd /home/ymy/deploy/tjhlp-gitea/deploy/runner && docker compose logs -f runner
|
||||
docker compose stop runner && docker compose start runner
|
||||
|
||||
# ★ 改了 deploy/runner/config.yaml 之后【必须重启 runner】才生效
|
||||
# (runner 只在启动时读一次配置; 只 `up -d` 不会重建容器)
|
||||
cd /home/ymy/deploy/tjhlp-gitea/deploy/runner && docker compose restart runner
|
||||
# ⚠️ 别让 deploy job 自己去重启 runner: 那等于掐断正在跑的这个 job
|
||||
# (重启日志里会出现 "cancelled in progress jobs during shutdown")。
|
||||
|
||||
# 平台日志(部署后排查)
|
||||
docker compose -f /home/ymy/deploy/tjhlp-gitea/deploy/compose.yaml logs -f gitea
|
||||
# 每次运行的完整日志在 仓库 → Actions 里
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 尚未验证的点(诚实清单)
|
||||
|
||||
**已经被真实运行确认的**(2026-09-21,共 5 次运行、最新一次成功):
|
||||
|
||||
- Gitea 1.27 的调度、日志回传、`concurrency`、`timeout-minutes`、`permissions`、job 级
|
||||
`if` + `contains(github.event.head_commit.message, ...)`、`github.sha` 都按预期工作;
|
||||
- job 镜像里有 `git 2.55` / `Python 3.10` / docker CLI;`container.network: host` 下回环与
|
||||
`10.80.42.185/QA` 都通;`docker compose` 可用;
|
||||
- runner 配置里的 `container.valid_volumes` 会被**真实调度路径**采纳(09-21 那次失败正是
|
||||
空白名单把挂载丢掉导致的)。
|
||||
|
||||
**仍然未知:**
|
||||
|
||||
1. **fork PR 的 workflow 审批行为**(安全前提):用一个测试 fork 发 PR 验证;在此之前按 §7.2
|
||||
第 3 条处理。
|
||||
2. **本轮收窄授权(2026-09-22)的端到端效果**:`docker_host: "-"` + job 自己申报
|
||||
`container.volumes` 这条路径,`act_runner exec` 验证不了——exec 有自己的
|
||||
`--container-daemon-socket` 默认值、也不读配置里的 `valid_volumes`(实测:exec 里未授权
|
||||
路径照样挂上、裸 job 照样有 socket),只能靠一次真实 push。判据:
|
||||
- **成功**:运行变绿 + `deploy/.state/last-deployed` = 本次 SHA;
|
||||
- **失败**:部署 job 在第一步 `cd /home/ymy/deploy/tjhlp-gitea` 就报错、**线上不受影响**
|
||||
(挂载没挂上 = 什么都还没做)→ 说明 `container.volumes` 没被采纳,`git revert` 回退到
|
||||
"全局 options + 白名单"的旧形态即可。
|
||||
- 想在**生产路径**上验证"裸 job 真的连 socket 也没有",需要临时加一个
|
||||
`on: workflow_dispatch` 的探针 workflow(本机只验证了"没有宿主路径"这一半 ✓)。
|
||||
3. **Actions 日志保留与体积**:`[actions] LOG_RETENTION_DAYS`(默认 365)与存储位置。
|
||||
4. **Gitea 是否支持"环境审批"**:若有 deployments/environments 的审批,可作为"自动部署但
|
||||
上线要点一下"的中间档。
|
||||
|
||||
---
|
||||
|
||||
## 10. 备选方案
|
||||
|
||||
| 方案 | 何时选 | 代价 |
|
||||
|---|---|---|
|
||||
| **B. 宿主二进制 + host 模式** | 不想给 job 容器挂 docker.sock / 不想维护 job 镜像 | 需要一次 sudo 装 systemd 单元;label 用 `self-hosted:host`(v0.6.1 配置里确认支持) |
|
||||
| **cron 轮询 + `auto-deploy.sh`** | fork PR 策略不可控,或不想让仓库里的代码在宿主上执行 | 延迟 ≤60s;无 UI/日志,只有落盘日志 |
|
||||
| **纯手工** | 推送频率低、每次都想人工确认 | 就是现在这样 |
|
||||
|
||||
cron 版的触发部分(其余复用 §5.2 的脚本):
|
||||
|
||||
```cron
|
||||
# crontab -e (ymy)
|
||||
* * * * * cd /home/ymy/deploy/tjhlp-gitea && git fetch -q origin main && \
|
||||
[ "$(git rev-parse origin/main)" != "$(cat deploy/.state/last-deployed 2>/dev/null)" ] && \
|
||||
./deploy/scripts/auto-deploy.sh "$(git rev-parse origin/main)" >> deploy/.state/cron.log 2>&1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. 落地顺序(一句话版)
|
||||
|
||||
```text
|
||||
4.1 部署克隆 → 4.2 拿仓库级令牌 + docker compose 起 runner → 4.3 只留 workflow_dispatch
|
||||
手动跑通并演练一次回滚 → 4.4 打开 push 触发 + main 分支保护
|
||||
```
|
||||
@@ -0,0 +1,251 @@
|
||||
# =============================================================================
|
||||
# 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 化: 站点元信息与页脚 ----------------------------------
|
||||
# 不填这些时, meta description 会保留 Gitea 自带的
|
||||
# "a painless self-hosted Git service", 页脚会显示 Powered by Gitea。
|
||||
# ★ 段名里的点必须编码成 _0X2E_ (config_env.go 的 GITEA__<段>__<键> 规则),
|
||||
# 即 app.ini 的 [ui.meta] 段要写成 GITEA__ui_0X2E_meta__XXX。
|
||||
GITEA__ui_0X2E_meta__AUTHOR: ${GITEA_META_AUTHOR:-同济大学高级语言程序设计课程}
|
||||
GITEA__ui_0X2E_meta__DESCRIPTION: ${GITEA_META_DESCRIPTION:-同济大学高级语言程序设计课程答疑平台}
|
||||
GITEA__ui_0X2E_meta__KEYWORDS: ${GITEA_META_KEYWORDS:-同济大学,高级语言程序设计,答疑,Issue}
|
||||
GITEA__other__SHOW_FOOTER_POWERED_BY: "false"
|
||||
GITEA__other__SHOW_FOOTER_VERSION: "false"
|
||||
|
||||
# --- 显示名称: Issue 发布者/评论者显示姓名, 而不是学号 ---------------
|
||||
# 导入用户时 full_name = 真实姓名、login = 学号(见 scripts/.../users.py);
|
||||
# Gitea 默认只显示 login, 打开这个开关后 Issue 的「由 X 创建」、正文/评论作者
|
||||
# 以及其它用 GetDisplayName() 的地方都改为显示 full_name, 没填姓名的回退学号。
|
||||
# 证据: models/user/user.go 的 GetDisplayName(); templates/shared/user/authorlink.tmpl。
|
||||
# 这是站点级设置, 没有按用户的开关。改完需重建容器(up -d)才生效。
|
||||
GITEA__ui__DEFAULT_SHOW_FULL_NAME: "true"
|
||||
|
||||
# --- 数据库 ---------------------------------------------------------
|
||||
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: 界面只提供 HTTP 克隆地址(加公钥时会提示"仅用于提交签名验证")。
|
||||
# 注意镜像自带 sshd(s6 服务 openssh), 容器内就在 22 上监听 —— 只是没有发布端口。
|
||||
# 启用要同时改 DISABLE_SSH / SSH_DOMAIN / SSH_PORT 并在 ports 里发布 2222:22,
|
||||
# 少改一处就会出现 ssh://git@localhost:22/... 这种坏地址: 见
|
||||
# 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"
|
||||
# 不做通行密钥(WebAuthn): 上游登录页的 passkey 区块只有 tw-hidden 的元素,
|
||||
# 浏览器不支持条件中介时就渲染成一个空方框; 关闭后区块不再输出。
|
||||
GITEA__service__ENABLE_PASSKEY_AUTHENTICATION: "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 email
|
||||
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"
|
||||
|
||||
# --- 出站代理: 显式给值挡掉 compose 的自动注入, 默认【不用代理】 --------
|
||||
# ★ docker compose 会把【运行 compose 的那个 shell 里】的 http_proxy/https_proxy
|
||||
# 自动注入容器。本机登录 shell 里是 127.0.0.1:7890, 而那个地址在容器里指向
|
||||
# 容器自己, 于是 Gitea 启动时 OIDC discovery 失败:
|
||||
# initOAuth2Sources() [E] Unable to register source: 高程统一身份认证 due to
|
||||
# proxyconnect tcp: dial tcp 127.0.0.1:7890: connect: connection refused
|
||||
# 后果: /user/oauth2/<认证源> 返回 404, 统一身份认证登录不可用(2026-09-11 实际踩到)。
|
||||
# 显式赋值可以挡住注入 —— 哪怕给的是空值。
|
||||
#
|
||||
# 不用代理的理由(2026-09-13 实测):
|
||||
# * 容器直连外网是通的 —— dl.gitea.com / api.github.com / codeload.github.com
|
||||
# 在容器里直接 curl 都是 200/301(github.com 主站直连会超时, 但平台不依赖它);
|
||||
# * 功能相关的出站只有 OIDC, 目标是 10.80.42.185, 容器内直连就是 200;
|
||||
# * 宿主 7890 那个代理是 ssh 转发的开发用代理, 只监听宿主 127.0.0.1,
|
||||
# 容器里连不上(127.0.0.1:7890 是容器自己; 10.80.42.185:7890 实测 connect refused)。
|
||||
# 将来真要给容器配代理, 必须是【容器可达】的地址(隧道绑 LAN 口, 或用 host 网络兜底),
|
||||
# 再在 deploy/.env 里给 GITEA_HTTP_PROXY。
|
||||
HTTP_PROXY: ${GITEA_HTTP_PROXY:-}
|
||||
HTTPS_PROXY: ${GITEA_HTTPS_PROXY:-}
|
||||
http_proxy: ${GITEA_HTTP_PROXY:-}
|
||||
https_proxy: ${GITEA_HTTPS_PROXY:-}
|
||||
NO_PROXY: ${GITEA_NO_PROXY:-localhost,127.0.0.1,::1,10.80.42.185,.local,.internal}
|
||||
no_proxy: ${GITEA_NO_PROXY:-localhost,127.0.0.1,::1,10.80.42.185,.local,.internal}
|
||||
|
||||
# --- 管理员限制 -----------------------------------------------------
|
||||
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
|
||||
# --- 定制覆盖层(Gitea 客制化, 见 customization/README.md) ------------
|
||||
# ★ 官方镜像里 GITEA_CUSTOM=/data/gitea, 所以定制文件对应
|
||||
# /data/gitea/{templates,public,options},
|
||||
# 不是 /data/gitea/custom(那是源码/二进制安装 WorkPath/custom 的写法,
|
||||
# 在容器里挂了不会生效)。
|
||||
# 分开挂三个子目录而不是整目录: 只读覆盖定制内容, 又不遮住同级的
|
||||
# conf/、log/、indexers/ 等容器自己管理的目录。
|
||||
# entrypoint 只在 /data/gitea 属主不是 git 时才 chown -R, 现有
|
||||
# ${GITEA_DATA_DIR}/gitea 属主已是 git, 不会去碰只读挂载。
|
||||
- ${GITEA_CUSTOM_DIR:?GITEA_CUSTOM_DIR is required}/templates:/data/gitea/templates:ro
|
||||
- ${GITEA_CUSTOM_DIR:?GITEA_CUSTOM_DIR is required}/public:/data/gitea/public:ro
|
||||
- ${GITEA_CUSTOM_DIR:?GITEA_CUSTOM_DIR is required}/options:/data/gitea/options:ro
|
||||
- /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'
|
||||
@@ -0,0 +1,10 @@
|
||||
# 复制成 .env 后填写(deploy/runner/.env 已 gitignore)
|
||||
#
|
||||
# RUNNER_REGISTRATION_TOKEN: 仓库 → Settings → Actions → Runners → 创建 Runner 时给的令牌。
|
||||
# 一次性, 用完即弃; 注册成功后身份存在 ./data/.runner, 重启不会再注册。
|
||||
RUNNER_REGISTRATION_TOKEN=
|
||||
|
||||
# 默认值在 compose.yaml 里, 需要时再覆盖
|
||||
#GITEA_INSTANCE_URL=https://cpp.tongji.sh/QA
|
||||
#RUNNER_NAME=tjhlp-gitea-1
|
||||
# runner 的 label 不在这里配: 以 config.yaml 的 runner.labels 为准(实测 env 会被忽略)
|
||||
@@ -0,0 +1,33 @@
|
||||
# Gitea Actions runner —— 跑在容器里, 由 docker 自己拉起(不需要 root, ymy 在 docker 组即可)。
|
||||
#
|
||||
# cd deploy/runner
|
||||
# cp .env.example .env # 填 RUNNER_REGISTRATION_TOKEN(仓库 → Settings → Actions → Runners)
|
||||
# docker compose up -d
|
||||
# docker compose logs -f runner
|
||||
#
|
||||
# 详见 ../ci-cd.md §4.2。注册结果存在 ./data/.runner, 重启不会重复注册。
|
||||
name: gitea-runner
|
||||
|
||||
services:
|
||||
runner:
|
||||
image: gitea/act_runner:latest # 实测 arm64 / v0.6.1
|
||||
container_name: gitea-runner
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
# 变量名与镜像里 /usr/local/bin/run.sh 一致
|
||||
GITEA_INSTANCE_URL: ${GITEA_INSTANCE_URL:-https://cpp.tongji.sh/QA}
|
||||
GITEA_RUNNER_REGISTRATION_TOKEN: ${RUNNER_REGISTRATION_TOKEN:?deploy/runner/.env 里给 RUNNER_REGISTRATION_TOKEN}
|
||||
GITEA_RUNNER_NAME: ${RUNNER_NAME:-tjhlp-gitea-1}
|
||||
# 注意: 不要在这里设 GITEA_RUNNER_LABELS —— act_runner 会警告
|
||||
# "Labels from command will be ignored, use labels defined in config file.",
|
||||
# label 以 config.yaml 的 runner.labels 为准(实测)。
|
||||
CONFIG_FILE: /config/config.yaml
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock # runner 用它拉起 job 容器
|
||||
- ./data:/data # 注册凭据 / 缓存(gitignore)
|
||||
- ./config.yaml:/config/config.yaml:ro
|
||||
logging:
|
||||
driver: json-file
|
||||
options:
|
||||
max-size: "10m"
|
||||
max-file: "3"
|
||||
@@ -0,0 +1,52 @@
|
||||
# act_runner 配置 —— 关键项都有注释, 依据是 act_runner v0.6.1 自带的 generate-config 输出。
|
||||
log:
|
||||
level: info
|
||||
|
||||
runner:
|
||||
file: /data/.runner # 与 compose.yaml 的 ./data 挂载对应; 注册后保存在这里
|
||||
capacity: 1 # 部署必须串行: 一次只跑一个 job
|
||||
timeout: 30m
|
||||
labels:
|
||||
# job 跑在容器里(network: host), 镜像用 Gitea 官方 runner 镜像(实测 arm64 可用)。
|
||||
# 换成 catthehacker/ubuntu:act-22.04 也可以; 记得同步 compose.yaml 的 GITEA_RUNNER_LABELS。
|
||||
- "self-hosted:docker://docker.gitea.com/runner-images:ubuntu-22.04"
|
||||
|
||||
container:
|
||||
# host: job 容器与宿主共用网络 —— verify.sh 里对 127.0.0.1:2080 的检查才有效,
|
||||
# 10.80.42.185 也不需要额外放行。
|
||||
# ⚠️ 这是 runner 级设置, 所以这个 runner 上的【每个】job 都共享宿主网络 —— 还没能
|
||||
# 收窄的一轴(见 ci-cd.md §7 残留项)。
|
||||
network: host
|
||||
# ★ 不把宿主 docker socket 自动挂进 job 容器(默认行为是自动挂 = 每个 job 都能拿到
|
||||
# root 等价能力)。改成"要用 docker 的 job 自己申报", 并受下面的白名单约束。
|
||||
docker_host: "-"
|
||||
# ★ job 允许申报的挂载白名单(gobwas/glob 匹配【挂载源路径】; [] = 一个都不许, ['**'] = 全放)。
|
||||
# 注意: 全局 options 里的 --volume 也过这道白名单 —— 不在表里的会被
|
||||
# "[xxx] is not a valid volume, will be ignored" 直接丢弃。2026-09-21 就因为这个
|
||||
# (当时 options 有挂载但白名单是默认空表)让 job 容器里看不到 /home/ymy/deploy,
|
||||
# 第一步 `cd /home/ymy/deploy/tjhlp-gitea` 就失败。
|
||||
#
|
||||
# 表里的四项分别对应:
|
||||
# /home/ymy/deploy job 里的工作目录(deploy job 申报, 可写)
|
||||
# /srv/gitea 部署克隆的 origin 是这里面的本地裸库; 不挂进去
|
||||
# `git fetch` 会报 "does not appear to be a git repository"
|
||||
# (2026-09-21 实际踩到), 只读
|
||||
# /var/run/docker.sock 部署要 `docker compose up -d`, 只给申报它的 job
|
||||
# /usr/bin/docker 等 docker CLI + compose 插件, 不依赖 job 镜像里带没带
|
||||
valid_volumes:
|
||||
- /home/ymy/deploy
|
||||
- /srv/gitea
|
||||
- /var/run/docker.sock
|
||||
- /usr/bin/docker
|
||||
- /usr/libexec/docker/cli-plugins
|
||||
# ★ 这里【故意不写】全局 options 挂载: 需要宿主路径/socket 的只有 deploy 这一个 job,
|
||||
# 由它在 .gitea/workflows/deploy.yml 的 container.volumes 里自己申报(见 ci-cd.md §5.1)。
|
||||
# 挂在这里等于这个 runner 上的每个 job(比如将来加的 PR 检查/测试)都白拿 socket = root。
|
||||
# 另外 act_runner 会自动挂 docker.sock, 再在 options 里挂一次会以
|
||||
# "Duplicate mount point: /var/run/docker.sock" 直接失败(2026-09-13 预演时实测),
|
||||
# 所以 docker_host: "-" 与 job 自己申报是配套的一对改动。
|
||||
force_pull: false # 镜像本地已有就不再拉
|
||||
|
||||
cache:
|
||||
enabled: true
|
||||
dir: /data/cache
|
||||
Executable
+160
@@ -0,0 +1,160 @@
|
||||
#!/usr/bin/env bash
|
||||
# main 自动部署 —— 由 .gitea/workflows/deploy.yml 调用, 也可以手工执行。
|
||||
#
|
||||
# ./auto-deploy.sh # 部署当前 checkout
|
||||
# ./auto-deploy.sh <sha> # 部署指定提交
|
||||
#
|
||||
# 流程: build.py(生成+校验) → docker compose up -d → custom/ 与上次成功部署的指纹不同
|
||||
# 就重启 gitea(模板/语言文件是启动时加载的) → 验证(verify.sh + check.sh)
|
||||
# → 成功则记下 .state/{last-deployed,custom-hash}
|
||||
# 任一步失败 → 回滚到 deploy/.state/last-deployed 记录的上一个成功提交并强制重启。
|
||||
# 只动代码与挂载文件; 数据库/`.env`/备份目录全程不参与(见 deploy/ci-cd.md §6)。
|
||||
set -euo pipefail
|
||||
|
||||
REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
|
||||
STATE_DIR="${REPO_DIR}/deploy/.state"
|
||||
STATE_FILE="${STATE_DIR}/last-deployed"
|
||||
HASH_FILE="${STATE_DIR}/custom-hash" # 上次成功部署时 customization/custom/ 的指纹
|
||||
PUBLIC_URL="${GITEA_PUBLIC_URL:-http://10.80.42.185/QA}"
|
||||
|
||||
# 本机/内网回环验证不能走代理, 否则会把 200 变成 502(见 deploy/README.md 陷阱 5)
|
||||
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY
|
||||
export no_proxy='*' NO_PROXY='*'
|
||||
# 只补齐标准路径(append): 不要把 /usr/bin 提到最前面 —— 宿主上 /usr/bin/python3 是 3.6
|
||||
export PATH="${PATH}:/usr/local/bin:/usr/bin:/bin"
|
||||
|
||||
# build.py 用了 `from __future__ import annotations`, 需要 python3 >= 3.7。
|
||||
# 宿主: python3 在 ~/.local/bin(3.14), /usr/bin/python3 是 3.6(Rocky 8);
|
||||
# job 容器(Ubuntu 22.04): /usr/bin/python3 是 3.10。所以不能盲信 PATH 里的第一个。
|
||||
# (第一次实测就踩到: 把 /usr/bin 提前 → 用 3.6 跑 build.py → SyntaxError → 语言文件没生成。)
|
||||
pick_python() {
|
||||
local c
|
||||
for c in "$(command -v python3 2>/dev/null)" /usr/local/bin/python3 /usr/bin/python3 "${HOME}/.local/bin/python3"; do
|
||||
[[ -n ${c} && -x ${c} ]] || continue
|
||||
if "${c}" -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 7) else 1)' 2>/dev/null; then
|
||||
printf '%s' "${c}"
|
||||
return 0
|
||||
fi
|
||||
done
|
||||
return 1
|
||||
}
|
||||
PY="$(pick_python)" || {
|
||||
echo "[auto-deploy] 找不到 >= 3.7 的 python3, 中止"
|
||||
exit 1
|
||||
}
|
||||
echo "[auto-deploy] python3: ${PY} ($("${PY}" -V 2>&1))"
|
||||
|
||||
mkdir -p "${STATE_DIR}"
|
||||
TARGET="${1:-$(git -C "${REPO_DIR}" rev-parse HEAD)}"
|
||||
PREV="$(cat "${STATE_FILE}" 2>/dev/null || true)"
|
||||
|
||||
# job 容器里是 root, 会把 clone 里新生成的文件留成 root 所有, 影响宿主上的手工 git 操作。
|
||||
# 结束时(无论成功失败)把所有权还回去。
|
||||
restore_owner() {
|
||||
[[ "$(id -u)" == 0 ]] || return 0
|
||||
chown -R "${DEPLOY_OWNER_UID:-1001}:${DEPLOY_OWNER_GID:-1001}" "${REPO_DIR}" 2>/dev/null || true
|
||||
}
|
||||
trap restore_owner EXIT
|
||||
|
||||
# workflow 的 concurrency 之外再加一道, 防止手工执行与 CI 撞车
|
||||
exec 9>"${STATE_DIR}/lock"
|
||||
flock -n 9 || {
|
||||
echo "[auto-deploy] 已有部署在跑, 本次退出"
|
||||
exit 0
|
||||
}
|
||||
|
||||
echo "[auto-deploy] 目标 ${TARGET} (上次成功部署: ${PREV:-无})"
|
||||
cd "${REPO_DIR}"
|
||||
|
||||
# customization/custom/ 的指纹: 模板、静态页、生成的语言文件都在里面。
|
||||
# 这些是 Gitea 启动时加载的, 变了必须重启容器才生效(README §3), 而 `compose up -d`
|
||||
# 只在 compose 配置变化时才重建容器 —— 所以自己比指纹, 变了就 restart。
|
||||
# ⚠️ 比的是【与上次成功部署的指纹】(.state/custom-hash), 不是 build.py 前后:
|
||||
# 后者只能发现语言文件被重新生成, 纯模板改动前后完全一样 → 永远不重启 → 容器继续
|
||||
# 用启动时加载的旧模板 → check.sh 断言失败 → 整个部署回滚。2026-09-22 实际踩到
|
||||
# (「提问指南」换地址那个提交就这么被回滚了)。
|
||||
custom_hash() {
|
||||
(cd customization/custom && find . -type f -exec sha256sum {} + | sort | sha256sum | cut -d' ' -f1)
|
||||
}
|
||||
|
||||
# compose 的 bind mount 源目录必须先存在【且属于当前用户】: 源目录不存在时 docker 会
|
||||
# 以 root 创建它, 之后 build.py 就写不进去(全新克隆第一次部署时真实踩到, 于是语言文件
|
||||
# 生成失败、「工单」回来了)。仓库里 custom/options/.gitkeep 从结构上避免这一点,
|
||||
# 这里再兜底检查一次, 失败就说清楚怎么办。
|
||||
prepare_custom_dirs() {
|
||||
local d
|
||||
for d in options public templates; do
|
||||
if [[ ! -d customization/custom/${d} ]]; then
|
||||
mkdir -p "customization/custom/${d}" 2>/dev/null || {
|
||||
echo "[auto-deploy] 无法创建 customization/custom/${d}" >&2
|
||||
return 1
|
||||
}
|
||||
fi
|
||||
if [[ ! -w customization/custom/${d} ]]; then
|
||||
echo "[auto-deploy] customization/custom/${d} 不可写 —— 很可能是 docker 以 root 创建过它。" >&2
|
||||
echo " 删除后重试(宿主上需 sudo; job 容器里是 root): rm -rf customization/custom/${d}" >&2
|
||||
return 1
|
||||
fi
|
||||
done
|
||||
}
|
||||
|
||||
deploy() {
|
||||
local force="${1:-}" now last
|
||||
prepare_custom_dirs || return 1
|
||||
"${PY}" customization/build.py || return 1 # 生成语言文件 + 规范 custom/ 权限
|
||||
"${PY}" customization/build.py --check || return 1 # 生成物/权限校验, 不过就中止, 不碰容器
|
||||
now="$(custom_hash)"
|
||||
(cd deploy && docker compose up -d) || return 1 # 幂等: 只有配置/挂载/镜像变化时才重建
|
||||
last="$(cat "${HASH_FILE}" 2>/dev/null || true)"
|
||||
if [[ -n ${force} || ${now} != "${last}" ]]; then
|
||||
if [[ -n ${force} ]]; then
|
||||
echo "[auto-deploy] 回滚路径: 重启 gitea, 让回退后的模板/语言文件生效"
|
||||
else
|
||||
echo "[auto-deploy] custom/ 与上次成功部署不同, 重启 gitea 使模板/语言文件生效"
|
||||
fi
|
||||
# 用 restart 而不是 up -d: compose 配置没变时 up -d 不重建容器, 而模板/语言文件
|
||||
# 是启动时加载的。restart 还会【重新解析 bind mount】—— 挂载源目录被「删掉再建」
|
||||
# (例如某个提交把 public/ 下的文件删光了, git 会顺手删掉空目录)之后, 容器里
|
||||
# 仍然挂着旧 inode(一个空目录), 只有重新 start 才会挂到新目录上。
|
||||
# 2026-09-22 实际踩到: 线上 /QA/assets/tjhlp/ask-guide.html 变成 404。
|
||||
(cd deploy && docker compose restart gitea) || return 1
|
||||
else
|
||||
echo "[auto-deploy] custom/ 与上次成功部署一致, 不重启"
|
||||
fi
|
||||
}
|
||||
|
||||
verify() {
|
||||
(cd deploy && ./scripts/verify.sh) || return 1 # 容器健康 + 本机 API + 经 Apache 反代
|
||||
if [[ -x ${REPO_DIR}/customization/check.sh ]]; then
|
||||
"${REPO_DIR}/customization/check.sh" "${PUBLIC_URL}" || return 1 # 定制断言
|
||||
else
|
||||
# 回滚到旧版本时那个版本可能还没有这个脚本 —— 那不是失败
|
||||
echo "[auto-deploy] (${TARGET} 这个版本没有 customization/check.sh, 跳过定制断言)"
|
||||
fi
|
||||
}
|
||||
|
||||
rollback() {
|
||||
if [[ -z ${PREV} ]]; then
|
||||
echo "[auto-deploy] 没有历史成功版本可回退, 保持现状"
|
||||
return 0
|
||||
fi
|
||||
echo "[auto-deploy] 回滚到 ${PREV}"
|
||||
# -f: 旧版本里可能没有 deploy/runner/* 这类文件, 它们在新版本是"未跟踪文件",
|
||||
# 会挡住普通 checkout(实测), 这里直接覆盖
|
||||
git checkout -f --detach "${PREV}"
|
||||
deploy force || true # force: 失败的那次可能已经用新模板重启过容器, 必须再重启回去
|
||||
verify || true
|
||||
}
|
||||
|
||||
# 包成一个函数再放进 if: 避免依赖 "&& 列表最后一个命令在 if 条件里是否触发 errexit" 这类细节
|
||||
pipeline() { deploy && verify; }
|
||||
|
||||
if pipeline; then
|
||||
echo "${TARGET}" >"${STATE_FILE}"
|
||||
custom_hash >"${HASH_FILE}" # 记下本次成功部署的 custom/ 指纹, 供下次比较
|
||||
echo "[auto-deploy] ✅ 部署成功 ${TARGET}"
|
||||
else
|
||||
echo "[auto-deploy] ❌ 部署或验证失败, 开始回滚"
|
||||
rollback
|
||||
exit 1
|
||||
fi
|
||||
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
|
||||
@@ -17,16 +17,36 @@
|
||||
issue-templates/
|
||||
├── general/ general 仓库使用
|
||||
│ └── .gitea/ISSUE_TEMPLATE/
|
||||
│ ├── config.yaml 禁止空白 Issue + 外部链接
|
||||
│ ├── config.yaml 禁止空白 Issue + 课程官网/提问规范链接
|
||||
│ ├── course-question.yaml 课程内容 / 知识点答疑
|
||||
│ ├── homework-help.yaml 编程作业问题
|
||||
│ └── env-setup.yaml 环境配置问题
|
||||
└── homework/ hwXX 作业仓库使用
|
||||
└── .gitea/ISSUE_TEMPLATE/
|
||||
├── config.yaml 禁止空白 Issue + 引导到 general
|
||||
├── config.yaml 禁止空白 Issue + 引导到 general + 课程官网链接
|
||||
└── homework-help.yaml 编程作业问题(无作业编号字段)
|
||||
```
|
||||
|
||||
## config.yaml 里的链接与占位符
|
||||
|
||||
`config.yaml` 的 `contact_links` 是「新建 Issue」页面上的引导入口, 目前指向**课程官网**
|
||||
(提问指南 / 课程信息), 把答疑平台和官网串起来。提问指南只在官网保留一份
|
||||
(`https://cpp.tongji.sh/Website/qa/ask/`, 平台内不再有副本); 课程官网地址是硬编码常量
|
||||
(`https://cpp.tongji.sh/Website/`), 换域名时两个 `config.yaml` 要一起改。
|
||||
|
||||
平台自身的链接用占位符, 避免把学期组织名写死:
|
||||
|
||||
| 占位符 | 替换为 | 来源 |
|
||||
|--------|--------|------|
|
||||
| `{{BASE_URL}}` | 面向同学的平台地址 | `scripts/settings.toml` 的 `gitea.public_url` |
|
||||
| `{{ORG}}` | 组织名(如 `tjhlp-2025f`) | 推送时的目标仓库 |
|
||||
| `{{REPO}}` | 仓库名(如 `hw01`) | 推送时的目标仓库 |
|
||||
|
||||
> 换学期只要新建组织、重跑 `setup init` / `create-homework`, 模板里的链接会自动跟着走。
|
||||
> `public_url` 没配时会保留占位符并打印警告, 不会推上一条坏链接。
|
||||
> 注意 `gitea.url`(CLI 调 API 用, 带内部端口)与 `public_url`(Apache 反代后的对外地址)
|
||||
> 是两回事, 写进模板的必须是后者。
|
||||
|
||||
## 模板说明
|
||||
|
||||
### general 仓库(3 个模板)
|
||||
@@ -97,10 +117,15 @@ uv run tjhlp repos init-templates tjhlp-2025f/hw01 --type homework
|
||||
|
||||
## 自定义
|
||||
|
||||
如需调整模板内容(如添加新的问题分类、修改引导文案), 直接编辑对应的 YAML 文件, 然后重新推送:
|
||||
如需调整模板内容(如添加新的问题分类、修改引导文案、更新 `config.yaml` 里的链接),
|
||||
直接编辑对应的 YAML 文件, 然后重新推送:
|
||||
|
||||
```bash
|
||||
# 已有仓库原地更新(general 与各 hwNN 都要推一次)
|
||||
uv run tjhlp repos init-templates tjhlp-2025f/general --type general
|
||||
uv run tjhlp repos init-templates tjhlp-2025f/hw01 --type homework
|
||||
```
|
||||
|
||||
推送会覆盖远端同名文件(走 API 的 create-or-update), 不需要重建仓库。
|
||||
|
||||
YAML 模板语法参考 [Gitea 文档](https://docs.gitea.com/usage/issue-pull-request-templates#syntax-for-yaml-template)。
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
blank_issues_enabled: false
|
||||
contact_links:
|
||||
- name: 课程主页
|
||||
url: https://example.com
|
||||
about: 访问课程主页获取有关资源
|
||||
- name: 常见问题汇总
|
||||
url: https://example.com/faq
|
||||
about: 提问前请先查阅常见问题汇总
|
||||
- name: 提问前必读 · 提问指南
|
||||
url: http://10.80.42.185/Website/qa/ask/
|
||||
about: 课程官网上的提问规范与做法。不合规范的提问很可能不会得到回答
|
||||
- name: 课程官网
|
||||
url: http://10.80.42.185/Website/
|
||||
about: 课程信息、作业说明、环境配置要求、常见问题
|
||||
|
||||
@@ -1,5 +1,11 @@
|
||||
blank_issues_enabled: false
|
||||
contact_links:
|
||||
- name: 一般性问题请到 general 仓库提问
|
||||
url: https://example.com
|
||||
url: "{{BASE_URL}}/{{ORG}}/general/issues/new/choose"
|
||||
about: 课程内容答疑、环境配置等非作业特定问题请到 general 仓库
|
||||
- name: 提问前必读 · 提问指南
|
||||
url: https://cpp.tongji.sh/Website/qa/ask/
|
||||
about: 课程官网上的提问规范与做法。不合规范的提问很可能不会得到回答
|
||||
- name: 课程官网
|
||||
url: https://cpp.tongji.sh/Website/
|
||||
about: 课程信息、作业说明、环境配置要求、常见问题
|
||||
|
||||
@@ -156,6 +156,20 @@ uv run tjhlp labels sync tjhlp-2025f/hw03
|
||||
uv run tjhlp webhooks list tjhlp-2025f/general
|
||||
```
|
||||
|
||||
### 显示名维护(学号-姓名)
|
||||
|
||||
Issue 页显示的是 `full_name`。OIDC 登录时会把 `full_name` 覆盖成认证源
|
||||
`FullNameClaimName` 对应的 claim(`display_name` = `学号-姓名`),因此**存量用户
|
||||
需要重新登录**才会刷新。若不想等用户重登,用 `tools/fix_full_name.py` 直接刷一遍:
|
||||
|
||||
```bash
|
||||
export TJHLP_GITEA_TOKEN=<token> # 或建 scripts/.secrets.toml
|
||||
uv run python tools/fix_full_name.py # dry-run,只打印
|
||||
uv run python tools/fix_full_name.py --apply # 实际写入
|
||||
```
|
||||
|
||||
脚本只改 `full_name`(成 `学号-姓名`),不动用户名/邮箱和团队归属;默认跳过 `admin`。
|
||||
|
||||
### 学期结束清理
|
||||
|
||||
```bash
|
||||
|
||||
@@ -1,5 +1,8 @@
|
||||
[default.gitea]
|
||||
url = "http://10.80.42.185:3000"
|
||||
url = "http://127.0.0.1:2080"
|
||||
# 同学实际访问的平台地址(Apache 反代 /QA -> 127.0.0.1:2080)。
|
||||
# 用于 Issue Template 等面向用户的链接; url 只用于 CLI 调 API。
|
||||
public_url = "https://cpp.tongji.sh/QA"
|
||||
email_domain = "tongji.edu.cn"
|
||||
default_org = ""
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@ from rich.console import Console
|
||||
|
||||
from tjhlp.client import GiteaClient, GiteaClientError
|
||||
from tjhlp.config import get_gitea_config
|
||||
from tjhlp.utils import parse_repo, push_templates, sync_labels
|
||||
from tjhlp.utils import parse_repo, push_templates, sync_labels, web_base_url
|
||||
|
||||
app = typer.Typer(no_args_is_help=True)
|
||||
console = Console()
|
||||
@@ -69,7 +69,7 @@ def create_homework(
|
||||
# 推送作业 Issue Templates
|
||||
console.print("\n推送 Issue Templates...")
|
||||
hw_tpl_dir = _TEMPLATES_DIR / "homework"
|
||||
n = push_templates(client, org, repo_name, hw_tpl_dir)
|
||||
n = push_templates(client, org, repo_name, hw_tpl_dir, web_base_url(cfg))
|
||||
console.print(f" 共推送 {n} 个模板文件")
|
||||
|
||||
# 同步 Labels
|
||||
@@ -120,7 +120,7 @@ def init_templates(
|
||||
|
||||
cfg = get_gitea_config()
|
||||
with GiteaClient(cfg) as client:
|
||||
n = push_templates(client, org_name, repo_name, tpl_dir)
|
||||
n = push_templates(client, org_name, repo_name, tpl_dir, web_base_url(cfg))
|
||||
console.print(f"\n共推送 {n} 个模板文件到 {repo}")
|
||||
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@ from rich.console import Console
|
||||
|
||||
from tjhlp.client import GiteaClient, GiteaClientError
|
||||
from tjhlp.config import get_gitea_config
|
||||
from tjhlp.utils import push_templates, sync_labels
|
||||
from tjhlp.utils import push_templates, sync_labels, web_base_url
|
||||
|
||||
app = typer.Typer(no_args_is_help=True)
|
||||
console = Console()
|
||||
@@ -86,7 +86,7 @@ def init(
|
||||
console.print("\n[bold]4. 推送 Issue Templates 到 general 仓库[/bold]")
|
||||
general_tpl_dir = _TEMPLATES_DIR / "general"
|
||||
if general_tpl_dir.exists():
|
||||
n = push_templates(client, org, "general", general_tpl_dir)
|
||||
n = push_templates(client, org, "general", general_tpl_dir, web_base_url(cfg))
|
||||
console.print(f" 共推送 {n} 个模板文件")
|
||||
else:
|
||||
console.print(f" [red]模板目录不存在: {general_tpl_dir}[/red]")
|
||||
|
||||
@@ -55,6 +55,10 @@ class GiteaConfig(BaseModel):
|
||||
token: SecretStr
|
||||
email_domain: str = "tongji.edu.cn"
|
||||
default_org: str = ""
|
||||
# 面向用户的访问地址(Apache 反代后的地址, 如 https://cpp.tongji.sh/QA)。
|
||||
# url 是 CLI 调 API 用的地址, 可能带内部端口, 不能直接写进 Issue Template 等
|
||||
# 给同学看的链接里; 留空时回退到 url。
|
||||
public_url: str = ""
|
||||
labels: list[LabelDef] = []
|
||||
|
||||
|
||||
|
||||
@@ -34,11 +34,38 @@ def parse_repo(repo: str) -> tuple[str, str]:
|
||||
# ---------------------------------------------------------------------------
|
||||
# Issue Template 推送
|
||||
# ---------------------------------------------------------------------------
|
||||
# 模板占位符: 让 Issue Template 不必硬编码学期组织名/访问地址
|
||||
# {{BASE_URL}} -> gitea.public_url(面向同学的地址)
|
||||
# {{ORG}} / {{REPO}} -> 推送目标
|
||||
TEMPLATE_PLACEHOLDERS = ("{{BASE_URL}}", "{{ORG}}", "{{REPO}}")
|
||||
|
||||
|
||||
def web_base_url(cfg: GiteaConfig) -> str:
|
||||
"""面向同学的平台访问地址: 优先 gitea.public_url, 否则退回 gitea.url。"""
|
||||
return (cfg.public_url or str(cfg.url)).rstrip("/")
|
||||
|
||||
|
||||
def render_template_placeholders(text: str, org: str, repo: str, web_base: str = "") -> str:
|
||||
"""替换 Issue Template 中的占位符, 返回渲染后的文本。"""
|
||||
base = (web_base or "").rstrip("/")
|
||||
if base:
|
||||
text = text.replace("{{BASE_URL}}", base)
|
||||
text = text.replace("{{ORG}}", org).replace("{{REPO}}", repo)
|
||||
left = [p for p in TEMPLATE_PLACEHOLDERS if p in text]
|
||||
if left:
|
||||
console.print(
|
||||
f"[yellow]警告: 模板中仍有未替换的占位符 {', '.join(left)}"
|
||||
f"(检查 settings.toml 的 gitea.public_url)[/yellow]"
|
||||
)
|
||||
return text
|
||||
|
||||
|
||||
def push_templates(
|
||||
client: GiteaClient,
|
||||
org: str,
|
||||
repo: str,
|
||||
template_dir: Path,
|
||||
web_base: str = "",
|
||||
) -> int:
|
||||
"""将本地 issue template 目录推送到远端仓库, 返回推送的文件数。"""
|
||||
count = 0
|
||||
@@ -51,7 +78,13 @@ def push_templates(
|
||||
if not filepath.is_file():
|
||||
continue
|
||||
remote_path = f".gitea/ISSUE_TEMPLATE/{filepath.name}"
|
||||
content_b64 = base64.b64encode(filepath.read_bytes()).decode()
|
||||
text = render_template_placeholders(
|
||||
filepath.read_text(encoding="utf-8"),
|
||||
org=org,
|
||||
repo=repo,
|
||||
web_base=web_base,
|
||||
)
|
||||
content_b64 = base64.b64encode(text.encode("utf-8")).decode()
|
||||
|
||||
existing = client.get_file_contents(org, repo, remote_path)
|
||||
if existing:
|
||||
|
||||
@@ -1,10 +1,17 @@
|
||||
"""utils.py 单元测试: parse_repo, compute_issue_stats"""
|
||||
"""utils.py 单元测试: parse_repo, compute_issue_stats, render_template_placeholders"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import pytest
|
||||
from pydantic import SecretStr
|
||||
|
||||
from tjhlp.utils import compute_issue_stats, parse_repo
|
||||
from tjhlp.config import GiteaConfig
|
||||
from tjhlp.utils import (
|
||||
compute_issue_stats,
|
||||
parse_repo,
|
||||
render_template_placeholders,
|
||||
web_base_url,
|
||||
)
|
||||
|
||||
# typer.Exit 在非 CLI 上下文中抛出 click.exceptions.Exit
|
||||
_EXIT_EXCEPTIONS = (SystemExit, Exception)
|
||||
@@ -103,3 +110,44 @@ class TestComputeIssueStats:
|
||||
]
|
||||
stats = compute_issue_stats(issues)
|
||||
assert stats["no_reply"] == 1
|
||||
|
||||
|
||||
class TestRenderTemplatePlaceholders:
|
||||
def test_replaces_all_placeholders(self):
|
||||
out = render_template_placeholders(
|
||||
'url: "{{BASE_URL}}/{{ORG}}/{{REPO}}/issues"',
|
||||
org="tjhlp-2025f",
|
||||
repo="hw01",
|
||||
web_base="https://cpp.tongji.sh/QA/",
|
||||
)
|
||||
assert out == 'url: "https://cpp.tongji.sh/QA/tjhlp-2025f/hw01/issues"'
|
||||
|
||||
def test_strips_trailing_slash_of_web_base(self):
|
||||
out = render_template_placeholders(
|
||||
"{{BASE_URL}}/assets/x.html", "org", "repo", "http://h/QA//"
|
||||
)
|
||||
assert out == "http://h/QA/assets/x.html"
|
||||
|
||||
def test_leaves_base_url_when_not_configured(self):
|
||||
# public_url 没配时应保留占位符(由 push_templates 打警告), 而不是生成坏链接
|
||||
out = render_template_placeholders("{{BASE_URL}}/x", "org", "repo")
|
||||
assert "{{BASE_URL}}" in out
|
||||
|
||||
def test_text_without_placeholders_is_unchanged(self):
|
||||
text = "blank_issues_enabled: false\n"
|
||||
assert render_template_placeholders(text, "org", "repo", "http://h") == text
|
||||
|
||||
|
||||
class TestWebBaseUrl:
|
||||
def _cfg(self, **kw):
|
||||
base = {"url": "https://cpp.tongji.sh:3000", "token": SecretStr("x")}
|
||||
return GiteaConfig(**{**base, **kw})
|
||||
|
||||
def test_prefers_public_url(self):
|
||||
assert (
|
||||
web_base_url(self._cfg(public_url="https://cpp.tongji.sh/QA/"))
|
||||
== "https://cpp.tongji.sh/QA"
|
||||
)
|
||||
|
||||
def test_falls_back_to_url(self):
|
||||
assert web_base_url(self._cfg()) == "https://cpp.tongji.sh:3000"
|
||||
|
||||
Reference in New Issue
Block a user