7 Commits
Author SHA256 Message Date
jkljkluiouio e96960c539 fix(测试): 改进用户创建测试并添加凭据导出验证
- 在测试中增加对凭据导出的验证
- 使用更安全的随机密码生成
- 添加对创建失败情况的测试覆盖
- 更新文档中的测试命令以包含临时目录参数
- 将临时测试目录添加到.gitignore
2026-04-29 13:44:00 +08:00
jkljkluiouio b8220a97c4 feat(users): 为用户创建命令添加随机密码生成和凭据导出功能
- 将初始密码从固定用户名改为随机生成
- 添加 CredentialRecord 数据结构记录创建结果
- 实现凭据 CSV 自动导出功能
- 更新相关文档说明
2026-04-29 13:44:00 +08:00
jkljkluiouio 7427bfe132 docs: 更新README文档内容' (#4)
- 移除邮件通知功能相关描述
- 修正用户创建时的密码策略说明
- 优化文档结构,删除重复内容
- 添加cmd环境下的命令示例
- 更新测试文件列表
2026-04-29 13:32:36 +08:00
jkljkluiouio 20d6d7eef5 docs: 更新README文档内容
- 移除邮件通知功能相关描述
- 修正用户创建时的密码策略说明
- 优化文档结构,删除重复内容
- 添加cmd环境下的命令示例
- 更新测试文件列表
2026-04-23 22:43:22 +08:00
jkljkluiouio 45dc819fda docker: 添加使用docker部署的方法用于快速测试 (#2)
添加使用docker部署的方法**用于快速测试**
路径于`deploy\compose`,目录下有相应部署指导文档

本次改动还将一些配置置为 example,在 git 中取消追踪**以免误操作将敏感信息提交**

Reviewed-on: https://cpp.tongji.sh:2080/jkljkluiouio/tjhlp-gitea/pulls/2
Co-authored-by: oierxjn <[email protected]>
Co-committed-by: oierxjn <[email protected]>
2026-04-23 22:20:52 +08:00
jkljkluiouio c338d39ed4 Merge pull request 'chore(ansible): 停止Git追踪服务器相关配置文件,改为添加示例配置文件' (#1) from chore/ansible into main
Reviewed-on: https://cpp.tongji.sh:2080/jkljkluiouio/tjhlp-gitea/pulls/1
2026-04-22 19:52:50 +08:00
jkljkluiouio 25c1fa9bd7 chore(ansible): 停止Git追踪服务器相关配置文件,改为添加示例配置文件
添加hosts.yml和all.yml的示例配置文件
更新README.md中的部署说明
将敏感配置文件添加到.gitignore
2026-04-21 15:16:46 +08:00
74 changed files with 1408 additions and 8921 deletions
-54
View File
@@ -1,54 +0,0 @@
# 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
+9 -11
View File
@@ -14,17 +14,8 @@ credentials_*.csv
*.pem *.pem
*.key *.key
# Deployment (docker compose) # Ansible
deploy/.env *.retry
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 # IDE
.idea/ .idea/
@@ -42,3 +33,10 @@ Thumbs.db
# OpenCode # OpenCode
.opencode/ .opencode/
# Server inventory
ansible/inventory/hosts.yml
ansible/inventory/group_vars/all.yml
# Docker Compose local config
deploy/compose/.env
+39 -40
View File
@@ -17,30 +17,43 @@
```text ```text
tjhlp-gitea/ tjhlp-gitea/
├── deploy/ Docker 部署与运维(Gitea + PostgreSQL) ├── ansible/ Ansible 自动化部署(Gitea + PostgreSQL)
├── customization/ Gitea 客制化(首页、中文术语、去 Gitea 化)与本地预览 ├── deploy/ 测试使用的部署方案(如 Docker Compose)
├── issue-templates/ Issue 模板(按仓库类型区分) ├── issue-templates/ Issue 模板(按仓库类型区分)
└── scripts/ Python CLI 管理工具 └── scripts/ Python CLI 管理工具
``` ```
## 快速开始 ## 快速开始
### 1. 部署服务器 ### 1. 选择部署方式
需要一台 Rocky Linux 8.10 服务器, 以及 Docker(含 compose 插件)。 本项目当前提供两种并行的单机部署方式:
- **Ansible**: 现有正式方案, 面向 Rocky Linux 8.10 主机, 直接安装 Gitea 二进制 + PostgreSQL + systemd
- **Docker Compose**: 测试方案, 面向单机容器部署, 默认只包含 Gitea + PostgreSQL, 提供管理员初始化脚本, 反向代理/TLS 由外部处理
如果你使用 Docker Compose, 先参考 [deploy/compose/README.md](deploy/compose/README.md) 完成服务启动, 然后再回到下面的“初始化平台”步骤。
### 2. 使用 Ansible 部署服务器
需要一台 Rocky Linux 8.10 服务器和本地安装的 Ansible。
```bash ```bash
cd deploy cd ansible
cp .env.example .env # 填写地址、密钥、密码 cp inventory/hosts.yml.example inventory/hosts.yml
docker compose config --quiet # 校验 compose 与 .env 插值 cp inventory/group_vars/all.yml.example inventory/group_vars/all.yml
docker compose up -d --build
sudo ./scripts/verify.sh # 体检
``` ```
完整的部署步骤(Docker 安装、外网代理、RPM 冲突处理), 以及 **备份 / 恢复 / 升级** 编辑 ansible/inventory/hosts.yml 填入服务器地址
流程, 见 [`deploy/README.md`](deploy/README.md)。 编辑 ansible/inventory/group_vars/all.yml 修改域名、密码等
### 2. 初始化平台 ```bash
ansible-playbook playbook.yml
```
部署完成后, Ansible 会自动创建管理员账号并输出访问地址。
### 3. 初始化平台
登录管理员账号, 在 **设置 -> 应用** 中创建 API Token, 然后: 登录管理员账号, 在 **设置 -> 应用** 中创建 API Token, 然后:
@@ -55,7 +68,7 @@ uv run tjhlp setup init --org tjhlp-2025f
这会创建课程组织、ta/students 团队、general 答疑仓库, 并推送 Issue Template 和预定义 Label。 这会创建课程组织、ta/students 团队、general 答疑仓库, 并推送 Issue Template 和预定义 Label。
### 3. 导入用户 ### 4. 导入用户
准备 CSV 文件(格式见 `scripts/example/members.csv`): 准备 CSV 文件(格式见 `scripts/example/members.csv`):
@@ -70,7 +83,7 @@ uv run tjhlp users create --file members.csv --org tjhlp-2025f
uv run tjhlp notify send-credentials --file credentials_*.csv uv run tjhlp notify send-credentials --file credentials_*.csv
``` ```
### 4. 创建作业仓库 ### 5. 创建作业仓库
```bash ```bash
uv run tjhlp repos create-homework --org tjhlp-2025f --number 1 uv run tjhlp repos create-homework --org tjhlp-2025f --number 1
@@ -90,8 +103,8 @@ uv run tjhlp repos create-homework --org tjhlp-2025f --number 1
```bash ```bash
cd scripts cd scripts
uv sync --extra dev uv sync --extra dev
uv run pytest tests/ -v # 运行全部测试 uv run pytest tests/ -v --basetemp .pytest_tmp # 运行全部测试
uv run pytest tests/ --cov=tjhlp --cov-report=term-missing # 带覆盖率 uv run pytest tests/ --cov=tjhlp --cov-report=term-missing --basetemp .pytest_tmp # 带覆盖率
``` ```
当前测试套件包含 99 个测试用例, 覆盖: 当前测试套件包含 99 个测试用例, 覆盖:
@@ -102,13 +115,13 @@ uv run pytest tests/ --cov=tjhlp --cov-report=term-missing # 带覆盖率
- **API 客户端**(client.py)— 使用 [respx](https://lundberg.github.io/respx/) mock HTTP 层, 测试分页、错误处理、404 返回 None - **API 客户端**(client.py)— 使用 [respx](https://lundberg.github.io/respx/) mock HTTP 层, 测试分页、错误处理、404 返回 None
- **命令集成**— 使用 Typer CliRunner + mock 测试 setup/users/repos 命令的完整流程 - **命令集成**— 使用 Typer CliRunner + mock 测试 setup/users/repos 命令的完整流程
### 部署配置检查 ### Ansible 静态检查
```bash ```bash
cd deploy cd ansible
docker compose config --quiet # 校验 compose 与 .env 插值 ansible-playbook --syntax-check playbook.yml # 语法检查
sudo ./scripts/verify.sh # 部署后验证(容器健康 + API + 反代) yamllint -c .yamllint.yml . # YAML 格式
./scripts/restore.sh --list # 查看可用备份及校验状态 ansible-lint playbook.yml # 最佳实践
``` ```
### Issue Templates 验证 ### Issue Templates 验证
@@ -117,31 +130,17 @@ sudo ./scripts/verify.sh # 部署后验证(容器健康 + API + 反
yamllint issue-templates/ # YAML 语法 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。 详见各子目录的 README。
## 技术栈 ## 技术栈
| 组件 | 技术选型 | | 组件 | 技术选型 |
| ------ | ---------- | | ------ | ---------- |
| Git 平台 | Gitea(Docker 容器) | | Git 平台 | Gitea(二进制 + systemd) |
| 数据库 | PostgreSQL 18(Docker 容器) | | 数据库 | PostgreSQL 18 |
| 服务器 | Rocky Linux 8.10 (aarch64) | | 服务器 | Rocky Linux 8.10 |
| 部署工具 | Docker Compose(见 `deploy/`) | | 部署工具 | Ansible / Docker Compose |
| 管理工具 | Python 3.14 + Typer + httpx + Pydantic + Dynaconf | | 管理工具 | Python 3.14 + Typer + httpx + Pydantic + Dynaconf |
| 包管理 | uv | | 包管理 | uv |
| 测试框架 | pytest + respx + pytest-cov | | 测试框架 | pytest + respx + pytest-cov |
| 代码检查 | ruff, yamllint | | 代码检查 | ruff, yamllint, ansible-lint |
+13
View File
@@ -0,0 +1,13 @@
---
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
+206
View File
@@ -0,0 +1,206 @@
# 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`)
+10
View File
@@ -0,0 +1,10 @@
[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
+42
View File
@@ -0,0 +1,42 @@
---
# =============================================================================
# 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: ""
@@ -0,0 +1,42 @@
---
# =============================================================================
# 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: ""
+7
View File
@@ -0,0 +1,7 @@
---
all:
hosts:
gitea-server:
ansible_host: 192.168.1.100 # 替换为实际服务器 IP
ansible_user: root # 替换为实际 SSH 用户
# ansible_ssh_private_key_file: ~/.ssh/id_rsa
+7
View File
@@ -0,0 +1,7 @@
---
all:
hosts:
gitea-server:
ansible_host: 192.168.1.100 # 替换为实际服务器 IP
ansible_user: root # 替换为实际 SSH 用户
# ansible_ssh_private_key_file: ~/.ssh/id_rsa
+54
View File
@@ -0,0 +1,54 @@
---
# =============================================================================
# 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
==========================================
+4
View File
@@ -0,0 +1,4 @@
---
collections:
- name: community.postgresql
version: ">=3.0.0"
+61
View File
@@ -0,0 +1,61 @@
---
# 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
+9
View File
@@ -0,0 +1,9 @@
---
- name: 重载 systemd
systemd:
daemon_reload: yes
- name: 重启 Gitea
systemd:
name: gitea
state: restarted
+100
View File
@@ -0,0 +1,100 @@
---
# 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"
+50
View File
@@ -0,0 +1,50 @@
---
# 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
+8
View File
@@ -0,0 +1,8 @@
---
# roles/gitea/tasks/main.yml
- name: 安装 Gitea
import_tasks: install.yml
- name: 配置 Gitea
import_tasks: configure.yml
+75
View File
@@ -0,0 +1,75 @@
; 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
@@ -0,0 +1,28 @@
[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
@@ -0,0 +1,5 @@
---
- name: 重启 PostgreSQL
systemd:
name: "postgresql-{{ postgresql_version }}"
state: restarted
+73
View File
@@ -0,0 +1,73 @@
---
# 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
@@ -0,0 +1,15 @@
# 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
-379
View File
@@ -1,379 +0,0 @@
# 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`)
-210
View File
@@ -1,210 +0,0 @@
#!/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())
-131
View File
@@ -1,131 +0,0 @@
#!/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}"
-15
View File
@@ -1,15 +0,0 @@
# 这个文件唯一的用途: 让 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, 它们不需要占位。
-15
View File
@@ -1,15 +0,0 @@
# 这个文件唯一的用途: 让 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)。
@@ -1,193 +0,0 @@
{{/*
导航栏, 整文件覆盖 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"}}
@@ -1,56 +0,0 @@
{{/*
首页(登录后的仪表盘)顶部的「本学期答疑入口」大卡片。
这是本课程自己的模板, 不是上游文件; 插入点见
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}}
-83
View File
@@ -1,83 +0,0 @@
{{/*
首页落地页, 整文件覆盖 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" .}}
@@ -1,92 +0,0 @@
{{/*
登录页, 整文件覆盖 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" .}}
@@ -1,22 +0,0 @@
{{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" .}}
-38
View File
@@ -1,38 +0,0 @@
#!/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 上游模板改动"
-1
View File
@@ -1 +0,0 @@
1.27.3
-16
View File
@@ -1,16 +0,0 @@
{
"_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 数"
}
}
@@ -1,14 +0,0 @@
{
"_comment": [
"按顺序对所有 zh-CN 译文做字面替换的规则。",
"适合「全站统一术语」这类批量修改, 新增术语时在这里加一条即可。",
"替换按数组顺序依次执行; 需要精修的具体条目请放到 locale_zh-CN.json(精确覆盖优先于本文件)。"
],
"rules": [
{
"note": "Issue 不译为「工单」, 直接沿用英文",
"from": "工单",
"to": "Issue"
}
]
}
-115
View File
@@ -1,115 +0,0 @@
# =============================================================================
# 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
-198
View File
@@ -1,198 +0,0 @@
#!/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
-11
View File
@@ -1,11 +0,0 @@
# 需要留快照的上游文件(相对 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
@@ -1,182 +0,0 @@
<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"}}
@@ -1,51 +0,0 @@
{{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" .}}
@@ -1,10 +0,0 @@
{{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" .}}
@@ -1,17 +0,0 @@
{{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" .}}
-187
View File
@@ -1,187 +0,0 @@
# 官网 ↔ 答疑平台 联动方案(提案)
> 这份文档是**给 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. 截图重拍的时间点(建议在平台定制部署上线后)。
-118
View File
@@ -1,118 +0,0 @@
# =============================================================================
# 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
View File
File diff suppressed because it is too large Load Diff
-603
View File
@@ -1,603 +0,0 @@
# 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 分支保护
```
-251
View File
@@ -1,251 +0,0 @@
# =============================================================================
# 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
+28
View File
@@ -0,0 +1,28 @@
# Copy this file to .env before running docker compose.
# Image versions
GITEA_IMAGE=gitea/gitea:1.24.7
POSTGRES_IMAGE=postgres:18
# Container runtime user
PUID=1000
PGID=1000
# Published ports on the Docker host
GITEA_HTTP_PORT=3000
# Public URL used by Gitea
# For local access you can keep localhost.
GITEA_DOMAIN=localhost
GITEA_ROOT_URL=http://localhost:3000/
# PostgreSQL settings
POSTGRES_DB=gitea
POSTGRES_USER=gitea
POSTGRES_PASSWORD=change_this_db_password
POSTGRES_SSL_MODE=disable
# First admin account used by init-admin.sh
GITEA_ADMIN_USERNAME=admin
GITEA_ADMIN_PASSWORD=ChangeMe!2026
GITEA_ADMIN_EMAIL=[email protected]
+140
View File
@@ -0,0 +1,140 @@
# Docker Compose 部署
- 目标: 单机容器部署 `Gitea + PostgreSQL`
- 不包含: Nginx、TLS 证书、外部对象存储、多节点编排
- 上层使用方式不变: 服务启动后仍然使用 `scripts/` 里的 `tjhlp` CLI 初始化课程组织、仓库、标签和 Webhook
## 文件说明
- `docker-compose.yml`: 启动 Gitea 与 PostgreSQL
- `.env.example`: 本地变量模板, 复制为 `.env` 后修改
- `init-admin.sh`: 读取 `.env` 中的管理员参数并初始化首个管理员账号
## 前置要求
- 已安装 Docker Engine
- 已安装 Docker Compose Plugin, 能执行 `docker compose`
- 目标机器开放 Gitea HTTP 访问端口
## 快速开始
```bash
cd deploy/compose
sudo cp .env.example .env
```
编辑 `.env`, 至少确认这些变量:
- `GITEA_IMAGE` / `POSTGRES_IMAGE`: 要使用的镜像版本
- `GITEA_ROOT_URL`: Gitea 对外访问地址, 必须与实际访问 URL 一致
- `GITEA_DOMAIN`: 对外访问域名或主机名
- `GITEA_HTTP_PORT`: 宿主机暴露的 Gitea 端口
- `POSTGRES_PASSWORD`: PostgreSQL 密码
- `PUID` / `PGID`: 容器内 Gitea 运行用户的 UID/GID, 默认 1000
- `GITEA_ADMIN_USERNAME`
- `GITEA_ADMIN_PASSWORD`
- `GITEA_ADMIN_EMAIL`
启动服务:
```bash
sudo docker compose up -d
sudo docker compose logs -f gitea
```
首次启动后, 运行管理员初始化脚本:
```bash
sudo sh ./init-admin.sh
```
脚本会:
- 从 `.env` 读取 `GITEA_ADMIN_USERNAME`、`GITEA_ADMIN_PASSWORD`、`GITEA_ADMIN_EMAIL`
- 等待 Gitea API 就绪
- 首次运行时创建管理员
- 再次运行时若管理员已存在则直接跳过
创建完成后, 访问 `GITEA_ROOT_URL`, 用 `.env` 中配置的管理员账号登录。
(不推荐Windows)如果你在 Windows 上使用 Docker Desktop, 建议通过 Git Bash 或 WSL 执行 `init-admin.sh`。
## 课程平台初始化
1. 登录 Gitea
2. 在“设置 -> 应用”中创建 API Token
3. 进入仓库 `scripts/` 目录
4. 配置 `.secrets.toml`
5. 执行:
```bash
uv sync
uv run tjhlp setup status
uv run tjhlp setup init --org tjhlp-2025f
```
如果是 Docker Compose 部署, 记得把 `scripts/settings.toml` 或环境变量中的 Gitea URL 指向 `GITEA_ROOT_URL`。
例如:
```bash
export TJHLP_GITEA_URL=http://localhost:3000
```
PowerShell:
```powershell
$env:TJHLP_GITEA_URL = "http://localhost:3000"
```
## 常用命令
启动:
```bash
sudo docker compose up -d
```
停止:
```bash
sudo docker compose down
```
查看日志:
```bash
sudo docker compose logs -f gitea
sudo docker compose logs -f postgres
```
升级镜像:
```bash
sudo docker compose pull
sudo docker compose up -d
```
## 数据持久化
本方案使用 Docker 命名卷:
- `gitea_data`: Gitea 仓库、附件、LFS、配置等数据
- `postgres_data`: PostgreSQL 数据目录
删除容器不会删除卷, 但执行带 `--volumes` 的 `docker compose down` 会清空数据。
## 与 Ansible 方案的关系
- `ansible/` 仍然是现有的主机直装方案
- `deploy/compose/` 是新增的单机容器方案
- 两者部署完成后, 上层 `scripts/` 的初始化和日常管理方式一致
## 注意事项
- `.env` 放环境差异和敏感参数, `docker-compose.yml` 保留项目默认策略配置
- 该方案默认只暴露 HTTP, 若要对外提供 HTTPS, 请在外部使用 Nginx/Caddy 等反向代理
- `GITEA_ROOT_URL` 配错时, Web 界面跳转、Webhook 和仓库链接通常会异常
- 如果宿主机已经占用 `3000`, 请调整 `.env` 中的端口映射
- PostgreSQL 默认不对宿主机暴露端口, 以减少额外暴露面
+49
View File
@@ -0,0 +1,49 @@
services:
postgres:
image: ${POSTGRES_IMAGE}
container_name: tjhlp-postgres
restart: unless-stopped
environment:
POSTGRES_DB: ${POSTGRES_DB}
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
volumes:
- postgres_data:/var/lib/postgresql
gitea:
image: ${GITEA_IMAGE}
container_name: tjhlp-gitea
restart: unless-stopped
depends_on:
- postgres
environment:
USER_UID: ${PUID}
USER_GID: ${PGID}
GITEA__database__DB_TYPE: postgres
GITEA__database__HOST: postgres:5432
GITEA__database__NAME: ${POSTGRES_DB}
GITEA__database__USER: ${POSTGRES_USER}
GITEA__database__PASSWD: ${POSTGRES_PASSWORD}
GITEA__database__SSL_MODE: ${POSTGRES_SSL_MODE}
GITEA__server__DOMAIN: ${GITEA_DOMAIN}
GITEA__server__HTTP_PORT: ${GITEA_HTTP_PORT}
GITEA__server__ROOT_URL: ${GITEA_ROOT_URL}
GITEA__server__LFS_START_SERVER: "true"
GITEA__repository__DEFAULT_BRANCH: main
GITEA__repository__DEFAULT_REPO_UNITS: repo.code,repo.issues
GITEA__security__INSTALL_LOCK: "true"
GITEA__service__DISABLE_REGISTRATION: "true"
GITEA__service__REQUIRE_SIGNIN_VIEW: "false"
GITEA__mailer__ENABLED: "false"
GITEA__webhook__ALLOWED_HOST_LIST: "*"
GITEA__webhook__SKIP_TLS_VERIFY: "false"
GITEA__api__ENABLE_SWAGGER: "true"
GITEA__api__MAX_RESPONSE_ITEMS: "100"
ports:
- "${GITEA_HTTP_PORT}:${GITEA_HTTP_PORT}"
volumes:
- gitea_data:/data
volumes:
postgres_data:
gitea_data:
+101
View File
@@ -0,0 +1,101 @@
#!/usr/bin/env sh
set -eu
SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
ENV_FILE="$SCRIPT_DIR/.env"
COMPOSE_FILE="$SCRIPT_DIR/docker-compose.yml"
log() {
printf '%s\n' "$*"
}
fail() {
printf 'Error: %s\n' "$*" >&2
exit 1
}
require_command() {
command -v "$1" >/dev/null 2>&1 || fail "missing required command: $1"
}
require_command docker
[ -f "$COMPOSE_FILE" ] || fail "docker-compose.yml not found in $SCRIPT_DIR"
[ -f "$ENV_FILE" ] || fail ".env not found in $SCRIPT_DIR; copy .env.example to .env first"
set -a
# shellcheck disable=SC1090
. "$ENV_FILE"
set +a
for var_name in GITEA_ADMIN_USERNAME GITEA_ADMIN_PASSWORD GITEA_ADMIN_EMAIL GITEA_ROOT_URL GITEA_HTTP_PORT PUID PGID; do
# 固定列表,非用户输入,无注入风险
eval "var_value=\${$var_name:-}"
[ -n "$var_value" ] || fail "required variable $var_name is missing or empty in .env"
done
dc() {
docker compose --file "$COMPOSE_FILE" --env-file "$ENV_FILE" "$@"
}
check_gitea_ready() {
dc exec -T gitea sh -c "
if command -v wget >/dev/null 2>&1; then
wget -q -O - 'http://127.0.0.1:${GITEA_HTTP_PORT}/api/v1/version' >/dev/null 2>&1
elif command -v curl >/dev/null 2>&1; then
curl -fsS 'http://127.0.0.1:${GITEA_HTTP_PORT}/api/v1/version' >/dev/null 2>&1
else
exit 1
fi
"
}
dc version >/dev/null 2>&1 || fail "docker compose is not available"
gitea_state=$(dc ps -q gitea 2>/dev/null || true)
[ -n "$gitea_state" ] || fail "gitea service is not created; run 'docker compose up -d' first"
db_state=$(dc ps -q postgres 2>/dev/null || true)
[ -n "$db_state" ] || fail "postgres service is not created; run 'docker compose up -d' first"
log "Waiting for Gitea to become ready at ${GITEA_ROOT_URL%/}/api/v1/version ..."
attempt=0
max_attempts=30
ready=0
# 最长约 60 秒,每 2 秒检查一次
while [ "$attempt" -lt "$max_attempts" ]; do
attempt=$((attempt + 1))
if check_gitea_ready; then
ready=1
break
fi
sleep 2
done
[ "$ready" -eq 1 ] || fail "Gitea did not become ready after $((max_attempts * 2)) seconds"
log "Creating admin user '${GITEA_ADMIN_USERNAME}' if needed ..."
create_output=$(
dc exec -T --user "${PUID}:${PGID}" gitea gitea admin user create \
--admin \
--username "$GITEA_ADMIN_USERNAME" \
--password "$GITEA_ADMIN_PASSWORD" \
--email "$GITEA_ADMIN_EMAIL" 2>&1
) || {
case "$create_output" in
*"already exists"*)
log "Admin user '${GITEA_ADMIN_USERNAME}' already exists; skipping."
exit 0
;;
*)
printf '%s\n' "$create_output" >&2
fail "failed to create admin user"
;;
esac
}
log "Admin user '${GITEA_ADMIN_USERNAME}' created successfully."
-21
View File
@@ -1,21 +0,0 @@
# =============================================================================
# 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'
-10
View File
@@ -1,10 +0,0 @@
# 复制成 .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 会被忽略)
-33
View File
@@ -1,33 +0,0 @@
# 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"
-52
View File
@@ -1,52 +0,0 @@
# 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
-160
View File
@@ -1,160 +0,0 @@
#!/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
-88
View File
@@ -1,88 +0,0 @@
#!/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"
-209
View File
@@ -1,209 +0,0 @@
#!/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
-120
View File
@@ -1,120 +0,0 @@
#!/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
+3 -28
View File
@@ -17,36 +17,16 @@
issue-templates/ issue-templates/
├── general/ general 仓库使用 ├── general/ general 仓库使用
│ └── .gitea/ISSUE_TEMPLATE/ │ └── .gitea/ISSUE_TEMPLATE/
│ ├── config.yaml 禁止空白 Issue + 课程官网/提问规范链接 │ ├── config.yaml 禁止空白 Issue + 外部链接
│ ├── course-question.yaml 课程内容 / 知识点答疑 │ ├── course-question.yaml 课程内容 / 知识点答疑
│ ├── homework-help.yaml 编程作业问题 │ ├── homework-help.yaml 编程作业问题
│ └── env-setup.yaml 环境配置问题 │ └── env-setup.yaml 环境配置问题
└── homework/ hwXX 作业仓库使用 └── homework/ hwXX 作业仓库使用
└── .gitea/ISSUE_TEMPLATE/ └── .gitea/ISSUE_TEMPLATE/
├── config.yaml 禁止空白 Issue + 引导到 general + 课程官网链接 ├── config.yaml 禁止空白 Issue + 引导到 general
└── homework-help.yaml 编程作业问题(无作业编号字段) └── 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 个模板) ### general 仓库(3 个模板)
@@ -117,15 +97,10 @@ uv run tjhlp repos init-templates tjhlp-2025f/hw01 --type homework
## 自定义 ## 自定义
如需调整模板内容(如添加新的问题分类、修改引导文案、更新 `config.yaml` 里的链接), 如需调整模板内容(如添加新的问题分类、修改引导文案), 直接编辑对应的 YAML 文件, 然后重新推送:
直接编辑对应的 YAML 文件, 然后重新推送:
```bash ```bash
# 已有仓库原地更新(general 与各 hwNN 都要推一次)
uv run tjhlp repos init-templates tjhlp-2025f/general --type general 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)。 YAML 模板语法参考 [Gitea 文档](https://docs.gitea.com/usage/issue-pull-request-templates#syntax-for-yaml-template)。
@@ -1,8 +1,8 @@
blank_issues_enabled: false blank_issues_enabled: false
contact_links: contact_links:
- name: 提问前必读 · 提问指南 - name: 课程主页
url: http://10.80.42.185/Website/qa/ask/ url: https://example.com
about: 课程官网上的提问规范与做法。不合规范的提问很可能不会得到回答 about: 访问课程主页获取有关资源
- name: 课程官网 - name: 常见问题汇总
url: http://10.80.42.185/Website/ url: https://example.com/faq
about: 课程信息、作业说明、环境配置要求、常见问题 about: 提问前请先查阅常见问题汇总
@@ -1,11 +1,5 @@
blank_issues_enabled: false blank_issues_enabled: false
contact_links: contact_links:
- name: 一般性问题请到 general 仓库提问 - name: 一般性问题请到 general 仓库提问
url: "{{BASE_URL}}/{{ORG}}/general/issues/new/choose" url: https://example.com
about: 课程内容答疑、环境配置等非作业特定问题请到 general 仓库 about: 课程内容答疑、环境配置等非作业特定问题请到 general 仓库
- name: 提问前必读 · 提问指南
url: https://cpp.tongji.sh/Website/qa/ask/
about: 课程官网上的提问规范与做法。不合规范的提问很可能不会得到回答
- name: 课程官网
url: https://cpp.tongji.sh/Website/
about: 课程信息、作业说明、环境配置要求、常见问题
+1
View File
@@ -9,6 +9,7 @@ build/
*.egg *.egg
# Pytest # Pytest
.pytest_tmp/
.coverage .coverage
# Secrets & credentials # Secrets & credentials
+21 -48
View File
@@ -1,6 +1,6 @@
# Python CLI 管理工具 # Python CLI 管理工具
`tjhlp` 是课程答疑平台的命令行管理工具, 通过 Gitea REST API 批量管理用户、组织、仓库、Webhook、Label, 并提供 Issue 统计和邮件通知功能。 `tjhlp` 是课程答疑平台的命令行管理工具, 通过 Gitea REST API 批量管理用户、组织、仓库、Webhook、Label, 并提供 Issue 统计功能。
## 前置要求 ## 前置要求
@@ -56,7 +56,7 @@ tjhlp
│ ├── init 一键初始化: 创建组织/团队/仓库/Labels/Webhook │ ├── init 一键初始化: 创建组织/团队/仓库/Labels/Webhook
│ └── status 检查 Gitea 连接状态 │ └── status 检查 Gitea 连接状态
├── users ├── users
│ ├── create 从 CSV 批量创建账号(随机密码) │ ├── create 从 CSV 批量创建账号(随机初始密码, 自动导出凭据 CSV)
│ ├── list 列出所有用户 │ ├── list 列出所有用户
│ └── delete 批量删除用户 │ └── delete 批量删除用户
├── orgs ├── orgs
@@ -77,12 +77,9 @@ tjhlp
├── labels ├── labels
│ ├── sync 同步预定义 Label 到仓库 │ ├── sync 同步预定义 Label 到仓库
│ └── list 列出仓库 Label │ └── list 列出仓库 Label
├── stats └── stats
│ ├── summary Issue 统计摘要 ├── summary Issue 统计摘要
│ └── export 导出 Issue 数据到 CSV └── export 导出 Issue 数据到 CSV
└── labels
├── sync 同步预定义 Label 到仓库
└── list 列出仓库 Label
``` ```
## 典型工作流 ## 典型工作流
@@ -103,29 +100,14 @@ uv run tjhlp setup init \
uv run tjhlp users create --file members.csv --org tjhlp-2025f uv run tjhlp users create --file members.csv --org tjhlp-2025f
``` ```
执行完成后会自动生成 `credentials_YYYYMMDD_HHMMSS.csv`, 包含账号、随机初始密码和处理状态。
## 典型工作流 `cmd` 可直接复制的写法:
### 学期初始化 ```cmd
```bash
# 1. 检查连接
uv run tjhlp setup status uv run tjhlp setup status
uv run tjhlp setup init --org tjhlp-2025f --webhook-url http://notify-server:8080/webhook --webhook-secret mysecret
# 2. 一键初始化(创建组织 + 团队 + general 仓库 + Labels + Webhook)
uv run tjhlp setup init \
--org tjhlp-2025f \
--webhook-url http://notify-server:8080/webhook \
--webhook-secret mysecret
# 3. 批量创建用户并分配到团队
uv run tjhlp users create --file members.csv --org tjhlp-2025f uv run tjhlp users create --file members.csv --org tjhlp-2025f
# 4. 发送账号密码邮件
uv run tjhlp notify send-credentials --file credentials_20250901_120000.csv
# 5. (可选)先预览邮件, 不实际发送
uv run tjhlp notify send-credentials --file credentials_*.csv --dry-run
``` ```
### 每次布置作业 ### 每次布置作业
@@ -138,6 +120,12 @@ uv run tjhlp repos create-homework \
--webhook-url http://notify-server:8080/webhook --webhook-url http://notify-server:8080/webhook
``` ```
`cmd` 可直接复制的写法:
```cmd
uv run tjhlp repos create-homework --org tjhlp-2025f --number 3 --desc "作业3: 链表操作" --webhook-url http://notify-server:8080/webhook
```
这会自动完成: 创建 `hw03` 仓库 -> 推送作业 Issue Template -> 同步 Labels -> 配置 Webhook -> 添加到 ta/students 团队。 这会自动完成: 创建 `hw03` 仓库 -> 推送作业 Issue Template -> 同步 Labels -> 配置 Webhook -> 添加到 ta/students 团队。
### 日常管理 ### 日常管理
@@ -156,20 +144,6 @@ uv run tjhlp labels sync tjhlp-2025f/hw03
uv run tjhlp webhooks list tjhlp-2025f/general 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 ```bash
@@ -188,10 +162,10 @@ id,name,role
``` ```
- `id` - 学号或工号, 同时作为 Gitea 用户名 - `id` - 学号或工号, 同时作为 Gitea 用户名
- `name` - 姓名, 作为 Gitea 的 full_name - `name` - 姓名, 作为 Gitea 的 `full_name`
- `role` - `student` 或 `ta`, 决定分配到哪个团队 - `role` - `student` 或 `ta`, 决定分配到哪个团队
- 邮箱自动生成为 `{id}@tongji.edu.cn` - 邮箱自动生成为 `{id}@tongji.edu.cn`
- **初始密码与用户名(学号/工号)相同**。 - 初始密码由程序随机生成, `users create` 执行后会自动导出凭据 CSV
示例文件见 `example/members.csv`。 示例文件见 `example/members.csv`。
@@ -223,15 +197,15 @@ uv sync --extra dev
### 运行测试 ### 运行测试
```bash ```bash
uv run pytest tests/ -v # 全部测试 uv run pytest tests/ -v --basetemp .pytest_tmp # 全部测试
uv run pytest tests/test_models.py # 只运行模型测试 uv run pytest tests/test_models.py --basetemp .pytest_tmp # 只运行模型测试
uv run pytest tests/ -k "password" # 按名称过滤 uv run pytest tests/ -k "password" --basetemp .pytest_tmp # 按名称过滤
``` ```
### 覆盖率报告 ### 覆盖率报告
```bash ```bash
uv run pytest tests/ --cov=tjhlp --cov-report=term-missing uv run pytest tests/ --cov=tjhlp --cov-report=term-missing --basetemp .pytest_tmp
``` ```
### 代码检查 ### 代码检查
@@ -285,7 +259,6 @@ scripts/
│ ├── test_models.py 数据模型测试 │ ├── test_models.py 数据模型测试
│ ├── test_config.py 配置校验测试 │ ├── test_config.py 配置校验测试
│ ├── test_utils.py 工具函数测试 │ ├── test_utils.py 工具函数测试
│ ├── test_pure_functions.py 纯函数测试
│ ├── test_client.py API 客户端测试 │ ├── test_client.py API 客户端测试
│ └── test_commands.py 命令集成测试 │ └── test_commands.py 命令集成测试
└── src/tjhlp/ └── src/tjhlp/
+1 -4
View File
@@ -1,8 +1,5 @@
[default.gitea] [default.gitea]
url = "http://127.0.0.1:2080" url = "http://10.80.42.185:3000"
# 同学实际访问的平台地址(Apache 反代 /QA -> 127.0.0.1:2080)。
# 用于 Issue Template 等面向用户的链接; url 只用于 CLI 调 API。
public_url = "https://cpp.tongji.sh/QA"
email_domain = "tongji.edu.cn" email_domain = "tongji.edu.cn"
default_org = "" default_org = ""
+3 -3
View File
@@ -9,7 +9,7 @@ from rich.console import Console
from tjhlp.client import GiteaClient, GiteaClientError from tjhlp.client import GiteaClient, GiteaClientError
from tjhlp.config import get_gitea_config from tjhlp.config import get_gitea_config
from tjhlp.utils import parse_repo, push_templates, sync_labels, web_base_url from tjhlp.utils import parse_repo, push_templates, sync_labels
app = typer.Typer(no_args_is_help=True) app = typer.Typer(no_args_is_help=True)
console = Console() console = Console()
@@ -69,7 +69,7 @@ def create_homework(
# 推送作业 Issue Templates # 推送作业 Issue Templates
console.print("\n推送 Issue Templates...") console.print("\n推送 Issue Templates...")
hw_tpl_dir = _TEMPLATES_DIR / "homework" hw_tpl_dir = _TEMPLATES_DIR / "homework"
n = push_templates(client, org, repo_name, hw_tpl_dir, web_base_url(cfg)) n = push_templates(client, org, repo_name, hw_tpl_dir)
console.print(f" 共推送 {n} 个模板文件") console.print(f" 共推送 {n} 个模板文件")
# 同步 Labels # 同步 Labels
@@ -120,7 +120,7 @@ def init_templates(
cfg = get_gitea_config() cfg = get_gitea_config()
with GiteaClient(cfg) as client: with GiteaClient(cfg) as client:
n = push_templates(client, org_name, repo_name, tpl_dir, web_base_url(cfg)) n = push_templates(client, org_name, repo_name, tpl_dir)
console.print(f"\n共推送 {n} 个模板文件到 {repo}") console.print(f"\n共推送 {n} 个模板文件到 {repo}")
+2 -2
View File
@@ -9,7 +9,7 @@ from rich.console import Console
from tjhlp.client import GiteaClient, GiteaClientError from tjhlp.client import GiteaClient, GiteaClientError
from tjhlp.config import get_gitea_config from tjhlp.config import get_gitea_config
from tjhlp.utils import push_templates, sync_labels, web_base_url from tjhlp.utils import push_templates, sync_labels
app = typer.Typer(no_args_is_help=True) app = typer.Typer(no_args_is_help=True)
console = Console() console = Console()
@@ -86,7 +86,7 @@ def init(
console.print("\n[bold]4. 推送 Issue Templates 到 general 仓库[/bold]") console.print("\n[bold]4. 推送 Issue Templates 到 general 仓库[/bold]")
general_tpl_dir = _TEMPLATES_DIR / "general" general_tpl_dir = _TEMPLATES_DIR / "general"
if general_tpl_dir.exists(): if general_tpl_dir.exists():
n = push_templates(client, org, "general", general_tpl_dir, web_base_url(cfg)) n = push_templates(client, org, "general", general_tpl_dir)
console.print(f" 共推送 {n} 个模板文件") console.print(f" 共推送 {n} 个模板文件")
else: else:
console.print(f" [red]模板目录不存在: {general_tpl_dir}[/red]") console.print(f" [red]模板目录不存在: {general_tpl_dir}[/red]")
+95 -4
View File
@@ -3,7 +3,8 @@
import csv import csv
import secrets import secrets
import string import string
from datetime import UTC, datetime from dataclasses import dataclass
from datetime import datetime
from pathlib import Path from pathlib import Path
import typer import typer
@@ -18,6 +19,17 @@ app = typer.Typer(no_args_is_help=True)
console = Console() console = Console()
@dataclass
class CredentialRecord:
id: str
name: str
role: str
email: str
status: str
password: str
message: str
def _read_members_csv(filepath: Path) -> list[MemberRecord]: def _read_members_csv(filepath: Path) -> list[MemberRecord]:
"""读取 members CSV 文件""" """读取 members CSV 文件"""
records: list[MemberRecord] = [] records: list[MemberRecord] = []
@@ -28,13 +40,45 @@ def _read_members_csv(filepath: Path) -> list[MemberRecord]:
return records return records
def _generate_password(length: int = 12) -> str:
"""
生成随机密码 \\
仅包含字母和数字
"""
alphabet = string.ascii_letters + string.digits
return "".join(secrets.choice(alphabet) for _ in range(length))
def _write_credentials_csv(records: list[CredentialRecord]) -> Path:
output_path = Path(f"credentials_{datetime.now():%Y%m%d_%H%M%S}.csv")
with output_path.open("w", encoding="utf-8-sig", newline="") as f:
writer = csv.DictWriter(
f,
fieldnames=["id", "name", "role", "email", "status", "password", "message"],
)
writer.writeheader()
for record in records:
writer.writerow(
{
"id": record.id,
"name": record.name,
"role": record.role,
"email": record.email,
"status": record.status,
"password": record.password,
"message": record.message,
}
)
return output_path
@app.command("create") @app.command("create")
def create_users( def create_users(
file: Path = typer.Option(..., "--file", "-f", help="成员名单 CSV 文件路径"), file: Path = typer.Option(..., "--file", "-f", help="成员名单 CSV 文件路径"),
org: str = typer.Option("", "--org", help="自动添加到指定组织的对应团队"), org: str = typer.Option("", "--org", help="自动添加到指定组织的对应团队"),
dry_run: bool = typer.Option(False, "--dry-run", help="仅预览, 不实际创建"), dry_run: bool = typer.Option(False, "--dry-run", help="仅预览, 不实际创建"),
) -> None: ) -> None:
"""从 CSV 批量创建用户账号(初始密码与用户名相同)""" """从 CSV 批量创建用户账号(随机初始密码, 自动导出凭据 CSV)"""
if not file.exists(): if not file.exists():
console.print(f"[red]文件不存在: {file}[/red]") console.print(f"[red]文件不存在: {file}[/red]")
raise typer.Exit(code=1) raise typer.Exit(code=1)
@@ -59,6 +103,8 @@ def create_users(
return return
stats = {"created": 0, "skipped": 0, "failed": 0} stats = {"created": 0, "skipped": 0, "failed": 0}
# 用于记录创建结果
credential_records: list[CredentialRecord] = []
with GiteaClient(cfg) as client: with GiteaClient(cfg) as client:
# 获取团队 ID(如果指定了组织) # 获取团队 ID(如果指定了组织)
@@ -69,23 +115,36 @@ def create_users(
students_team = client.get_team_by_name(org, "students") students_team = client.get_team_by_name(org, "students")
for member in members: for member in members:
# 检查用户是否已存在 # 检查用户是否已存在,仅校验用户名是否存在
existing = client.get_user(member.username) existing = client.get_user(member.username)
if existing: if existing:
console.print(f" [yellow]跳过[/yellow] {member.username}({member.name})- 已存在") console.print(f" [yellow]跳过[/yellow] {member.username}({member.name})- 已存在")
stats["skipped"] += 1 stats["skipped"] += 1
credential_records.append(
CredentialRecord(
id=member.id,
name=member.name,
role=member.role,
email=member.email,
status="skipped",
password="",
message="user already exists",
)
)
continue continue
try: try:
password = _generate_password()
client.create_user( client.create_user(
username=member.username, username=member.username,
password=member.username, password=password,
email=member.email, email=member.email,
full_name=member.name, full_name=member.name,
must_change_password=True, must_change_password=True,
) )
console.print(f" [green]创建[/green] {member.username}({member.name})") console.print(f" [green]创建[/green] {member.username}({member.name})")
stats["created"] += 1 stats["created"] += 1
message = "created"
# 添加到团队 # 添加到团队
if org: if org:
@@ -95,14 +154,46 @@ def create_users(
client.add_team_member(team.id, member.username) client.add_team_member(team.id, member.username)
except GiteaClientError as e: except GiteaClientError as e:
console.print(f" [yellow]添加到团队失败: {e.message}[/yellow]") console.print(f" [yellow]添加到团队失败: {e.message}[/yellow]")
message = f"created; team assignment failed: {e.message}"
credential_records.append(
CredentialRecord(
id=member.id,
name=member.name,
role=member.role,
email=member.email,
status="created",
password=password,
message=message,
)
)
except GiteaClientError as e: except GiteaClientError as e:
console.print(f" [red]失败[/red] {member.username}({member.name}): {e.message}") console.print(f" [red]失败[/red] {member.username}({member.name}): {e.message}")
stats["failed"] += 1 stats["failed"] += 1
credential_records.append(
CredentialRecord(
id=member.id,
name=member.name,
role=member.role,
email=member.email,
status="failed",
password="",
message=e.message,
)
)
try:
output_path = _write_credentials_csv(credential_records)
except OSError as e:
console.print(f"[red]凭据导出失败: {e}[/red]")
console.print("[yellow]用户创建结果可能已部分生效, 请先检查 Gitea 中的实际状态, 不要直接重试整批导入。[/yellow]")
raise typer.Exit(code=1) from e
console.print( console.print(
f"\n完成: 创建 {stats['created']}, 跳过 {stats['skipped']}, 失败 {stats['failed']}" f"\n完成: 创建 {stats['created']}, 跳过 {stats['skipped']}, 失败 {stats['failed']}"
) )
console.print(f"凭据已导出: {output_path}")
@app.command("list") @app.command("list")
-4
View File
@@ -55,10 +55,6 @@ class GiteaConfig(BaseModel):
token: SecretStr token: SecretStr
email_domain: str = "tongji.edu.cn" email_domain: str = "tongji.edu.cn"
default_org: str = "" default_org: str = ""
# 面向用户的访问地址(Apache 反代后的地址, 如 https://cpp.tongji.sh/QA)。
# url 是 CLI 调 API 用的地址, 可能带内部端口, 不能直接写进 Issue Template 等
# 给同学看的链接里; 留空时回退到 url。
public_url: str = ""
labels: list[LabelDef] = [] labels: list[LabelDef] = []
+1 -34
View File
@@ -34,38 +34,11 @@ def parse_repo(repo: str) -> tuple[str, str]:
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
# Issue Template 推送 # 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( def push_templates(
client: GiteaClient, client: GiteaClient,
org: str, org: str,
repo: str, repo: str,
template_dir: Path, template_dir: Path,
web_base: str = "",
) -> int: ) -> int:
"""将本地 issue template 目录推送到远端仓库, 返回推送的文件数。""" """将本地 issue template 目录推送到远端仓库, 返回推送的文件数。"""
count = 0 count = 0
@@ -78,13 +51,7 @@ def push_templates(
if not filepath.is_file(): if not filepath.is_file():
continue continue
remote_path = f".gitea/ISSUE_TEMPLATE/{filepath.name}" remote_path = f".gitea/ISSUE_TEMPLATE/{filepath.name}"
text = render_template_placeholders( content_b64 = base64.b64encode(filepath.read_bytes()).decode()
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) existing = client.get_file_contents(org, repo, remote_path)
if existing: if existing:
+94 -13
View File
@@ -2,7 +2,6 @@
from __future__ import annotations from __future__ import annotations
import csv
from pathlib import Path from pathlib import Path
from unittest.mock import MagicMock, patch from unittest.mock import MagicMock, patch
@@ -11,6 +10,7 @@ from pydantic import HttpUrl, SecretStr
from typer.testing import CliRunner from typer.testing import CliRunner
from tjhlp.cli import app from tjhlp.cli import app
from tjhlp.client import GiteaClient, GiteaClientError
from tjhlp.config import GiteaConfig, LabelDef from tjhlp.config import GiteaConfig, LabelDef
from tjhlp.models import GiteaRepo, GiteaTeam, GiteaUser from tjhlp.models import GiteaRepo, GiteaTeam, GiteaUser
@@ -104,9 +104,16 @@ class TestUsersCreateDryRun:
class TestUsersCreate: class TestUsersCreate:
@patch("tjhlp.commands.users.GiteaClient") @patch("tjhlp.commands.users.GiteaClient")
@patch("tjhlp.commands.users.get_gitea_config") @patch("tjhlp.commands.users.get_gitea_config")
def test_creates_users(self, mock_get_cfg, mock_client_cls, mock_config, tmp_path: Path): def test_creates_users(
self,
mock_get_cfg: MagicMock,
mock_client_cls: MagicMock,
mock_config: GiteaConfig,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch
):
mock_get_cfg.return_value = mock_config mock_get_cfg.return_value = mock_config
client = MagicMock() client = MagicMock(spec=GiteaClient)
client.__enter__ = MagicMock(return_value=client) client.__enter__ = MagicMock(return_value=client)
client.__exit__ = MagicMock(return_value=False) client.__exit__ = MagicMock(return_value=False)
client.get_user.return_value = None # user doesn't exist client.get_user.return_value = None # user doesn't exist
@@ -116,6 +123,7 @@ class TestUsersCreate:
csv_file = tmp_path / "members.csv" csv_file = tmp_path / "members.csv"
csv_file.write_text("id,name,role\n2659999,赵一伤,student\n", encoding="utf-8") csv_file.write_text("id,name,role\n2659999,赵一伤,student\n", encoding="utf-8")
monkeypatch.chdir(tmp_path)
result = runner.invoke( result = runner.invoke(
app, app,
@@ -125,22 +133,44 @@ class TestUsersCreate:
"--file", "--file",
str(csv_file), str(csv_file),
], ],
catch_exceptions=False,
) )
assert result.exit_code == 0 assert result.exit_code == 0
assert "创建" in result.output assert "创建" in result.output
client.create_user.assert_called_once_with( assert "凭据已导出:" in result.output
username="2659999", client.create_user.assert_called_once()
password="2659999", call_kwargs = client.create_user.call_args.kwargs
email="[email protected]", assert call_kwargs["username"] == "2659999"
full_name="赵一伤", assert call_kwargs["email"] == "[email protected]"
must_change_password=True, assert call_kwargs["full_name"] == "赵一伤"
) assert call_kwargs["must_change_password"] is True
assert call_kwargs["password"] != "2659999"
assert len(call_kwargs["password"]) >= 12
credential_files = list(tmp_path.glob("credentials_*.csv"))
assert len(credential_files) == 1
content = credential_files[0].read_text(encoding="utf-8-sig")
assert "created" in content
assert "2659999" in content
@patch("tjhlp.commands.users.GiteaClient") @patch("tjhlp.commands.users.GiteaClient")
@patch("tjhlp.commands.users.get_gitea_config") @patch("tjhlp.commands.users.get_gitea_config")
def test_skips_existing_user(self, mock_get_cfg, mock_client_cls, mock_config, tmp_path: Path): def test_skips_existing_user(
self,
mock_get_cfg: MagicMock,
mock_client_cls: MagicMock,
mock_config: GiteaConfig,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch
):
"""
测试内容:用户已存在时,是否正常导出凭据,且凭据中包含已存在的用户名和错误信息
预期:
- 用户已存在时,凭据导出文件中包含已存在的用户名和错误信息
"""
mock_get_cfg.return_value = mock_config mock_get_cfg.return_value = mock_config
client = MagicMock() client = MagicMock(spec=GiteaClient)
client.__enter__ = MagicMock(return_value=client) client.__enter__ = MagicMock(return_value=client)
client.__exit__ = MagicMock(return_value=False) client.__exit__ = MagicMock(return_value=False)
client.get_user.return_value = GiteaUser(id=1, login="2659999") # already exists client.get_user.return_value = GiteaUser(id=1, login="2659999") # already exists
@@ -148,11 +178,62 @@ class TestUsersCreate:
csv_file = tmp_path / "members.csv" csv_file = tmp_path / "members.csv"
csv_file.write_text("id,name,role\n2659999,赵一伤,student\n", encoding="utf-8") csv_file.write_text("id,name,role\n2659999,赵一伤,student\n", encoding="utf-8")
monkeypatch.chdir(tmp_path)
result = runner.invoke(app, ["users", "create", "--file", str(csv_file)]) result = runner.invoke(
app,
["users", "create", "--file", str(csv_file)],
catch_exceptions=False,
)
assert result.exit_code == 0 assert result.exit_code == 0
assert "跳过" in result.output assert "跳过" in result.output
client.create_user.assert_not_called() client.create_user.assert_not_called()
credential_files = list(tmp_path.glob("credentials_*.csv"))
assert len(credential_files) == 1
content = credential_files[0].read_text(encoding="utf-8-sig")
assert "skipped" in content
assert "user already exists" in content
@patch("tjhlp.commands.users.GiteaClient")
@patch("tjhlp.commands.users.get_gitea_config")
def test_exports_failed_user(
self,
mock_get_cfg: MagicMock,
mock_client_cls: MagicMock,
mock_config: GiteaConfig,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch
):
"""
测试内容:用户创建失败时,凭据是否正常导出
预期:
- 用户创建失败时,凭据导出文件中包含失败的用户名和错误信息
"""
mock_get_cfg.return_value = mock_config
client = MagicMock(spec=GiteaClient)
client.__enter__ = MagicMock(return_value=client)
client.__exit__ = MagicMock(return_value=False)
client.get_user.return_value = None
client.create_user.side_effect = GiteaClientError(400, "PasswordIsRequired")
mock_client_cls.return_value = client
csv_file = tmp_path / "members.csv"
csv_file.write_text("id,name,role\n2659999,赵一伤,student\n", encoding="utf-8")
monkeypatch.chdir(tmp_path)
result = runner.invoke(
app,
["users", "create", "--file", str(csv_file)],
catch_exceptions=False,
)
assert result.exit_code == 0
credential_files = list(tmp_path.glob("credentials_*.csv"))
assert len(credential_files) == 1
content = credential_files[0].read_text(encoding="utf-8-sig")
assert "failed" in content
assert "PasswordIsRequired" in content
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
+2 -50
View File
@@ -1,17 +1,10 @@
"""utils.py 单元测试: parse_repo, compute_issue_stats, render_template_placeholders""" """utils.py 单元测试: parse_repo, compute_issue_stats"""
from __future__ import annotations from __future__ import annotations
import pytest import pytest
from pydantic import SecretStr
from tjhlp.config import GiteaConfig from tjhlp.utils import compute_issue_stats, parse_repo
from tjhlp.utils import (
compute_issue_stats,
parse_repo,
render_template_placeholders,
web_base_url,
)
# typer.Exit 在非 CLI 上下文中抛出 click.exceptions.Exit # typer.Exit 在非 CLI 上下文中抛出 click.exceptions.Exit
_EXIT_EXCEPTIONS = (SystemExit, Exception) _EXIT_EXCEPTIONS = (SystemExit, Exception)
@@ -110,44 +103,3 @@ class TestComputeIssueStats:
] ]
stats = compute_issue_stats(issues) stats = compute_issue_stats(issues)
assert stats["no_reply"] == 1 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"