SHA256
53116f7a23797be6f67db69822ac196633ae0c02bde3e133cf957ac61bee16d4
deploy / deploy (push) Successful in 11s
事故经过(2026-09-22): 「提问指南」换地址那个提交推送后 CI 挂了, auto-deploy 回滚。 check.sh 报「没找到官网提问指南链接 / 仍有旧地址」—— 但脚本确实把部署克隆同步到了新 提交、语言文件也重新生成了。原来 deploy() 比较的是 build.py 运行【前后】的指纹: 那只能 发现语言文件被重新生成, 纯模板改动前后完全一样 → 从不重启 → 容器继续用启动时加载的旧 模板 → 断言失败 → 整个部署被判失败并回滚。也就是说: 任何只改模板的提交都必然挂 CI。 修法: 把指纹记在 deploy/.state/custom-hash 里, 与【上次成功部署】的指纹比较, 不同就 restart gitea(restart 而不是 up -d: compose 配置没变时 up -d 不重建容器)。rollback 路径 改成 deploy force 无条件重启 —— 失败的那次可能已经用新模板重启过容器, 回滚必须再重启 回去, 顺便也修好下面这个副作用。 顺带修一个 bind mount 的坑: 挂载【源目录】被「删掉再建」后容器里挂的还是旧 inode(空 目录)。这次事故里 public/ 下的文件被删光、git 顺手删掉空目录, 于是线上 /QA/assets/tjhlp/ask-guide.html 变成 404。已在预览上复现([B] 404 → restart 后 [C] 200), restart 会重新解析挂载, 所以上面的修法同时把它修好。 验证(不碰生产的沙箱, 假 docker + 桩 verify/check): 1 全新状态首次部署 → up -d + restart ✓ 2 什么都没改再部署 → 不重启 ✓ 3 只改一个模板文件 → 重启 ✓(这次的回归点) 4 之后再来一次 → 不重启 ✓ 5 check 失败 → 回滚 → checkout PREV + 强制 restart ✓, 状态文件不被污染 ✓ 另外 check.sh / preview.sh 的失败信息里加了「模板改动要重启才生效」的提示, 并把 ci-cd.md §5.2(脚本清单+为什么必须 restart)与 README §12 速查表同步更新。
TJHLP-Gitea
同济大学高级语言程序设计课程(Tongji High-level Language Programming)基于 Gitea 的答疑平台。
项目背景
为课程搭建自托管的 Git 答疑平台, 提供以下能力:
- 学生通过 Issue 提问, 结构化的 Issue Template 引导提问前思考、规范问题描述
- 助教通过 Label 标记重复 / 低质问题, 管理答疑流程
- Webhook 将 Issue 动态推送到 IM(如 QQ 机器人), 助教无需轮询平台即可收到通知
- Python CLI 工具批量管理用户、仓库、标签等, 降低运维负担
选择 Gitea 自托管而非 GitHub Classroom / Piazza 等方案, 是因为国内网络环境限制, 且需要定制化功能。
项目结构
tjhlp-gitea/
├── deploy/ Docker 部署与运维(Gitea + PostgreSQL)
├── customization/ Gitea 客制化(首页、中文术语、去 Gitea 化)与本地预览
├── issue-templates/ Issue 模板(按仓库类型区分)
└── scripts/ Python CLI 管理工具
快速开始
1. 部署服务器
需要一台 Rocky Linux 8.10 服务器, 以及 Docker(含 compose 插件)。
cd deploy
cp .env.example .env # 填写地址、密钥、密码
docker compose config --quiet # 校验 compose 与 .env 插值
docker compose up -d --build
sudo ./scripts/verify.sh # 体检
完整的部署步骤(Docker 安装、外网代理、RPM 冲突处理), 以及 备份 / 恢复 / 升级
流程, 见 deploy/README.md。
2. 初始化平台
登录管理员账号, 在 设置 -> 应用 中创建 API Token, 然后:
cd scripts
cp .secrets.toml.example .secrets.toml
# 编辑 .secrets.toml, 填入 gitea_token 和 SMTP 配置
uv sync
uv run tjhlp setup init --org tjhlp-2025f
这会创建课程组织、ta/students 团队、general 答疑仓库, 并推送 Issue Template 和预定义 Label。
3. 导入用户
准备 CSV 文件(格式见 scripts/example/members.csv):
id,name,role
2659999,赵一伤,student
10001,李四催,ta
uv run tjhlp users create --file members.csv --org tjhlp-2025f
uv run tjhlp notify send-credentials --file credentials_*.csv
4. 创建作业仓库
uv run tjhlp repos create-homework --org tjhlp-2025f --number 1
仓库设计
| 仓库 | 用途 | Issue Template |
|---|---|---|
{org}/general |
一般性问题: 课程内容答疑、环境配置 | 课程答疑 / 作业问题 / 环境配置 |
{org}/hw01 ... |
各次作业的特定问题 | 仅作业问题模板 |
开发与测试
Python CLI 测试
cd scripts
uv sync --extra dev
uv run pytest tests/ -v # 运行全部测试
uv run pytest tests/ --cov=tjhlp --cov-report=term-missing # 带覆盖率
当前测试套件包含 99 个测试用例, 覆盖:
- 数据模型(models.py)— 100% 覆盖率
- 配置校验(config.py)— Pydantic 模型、Label 颜色验证、必填字段
- 纯函数— 密码生成、CSV 解析、邮件模板构建、HTML 转义防护
- API 客户端(client.py)— 使用 respx mock HTTP 层, 测试分页、错误处理、404 返回 None
- 命令集成— 使用 Typer CliRunner + mock 测试 setup/users/repos 命令的完整流程
部署配置检查
cd deploy
docker compose config --quiet # 校验 compose 与 .env 插值
sudo ./scripts/verify.sh # 部署后验证(容器健康 + API + 反代)
./scripts/restore.sh --list # 查看可用备份及校验状态
Issue Templates 验证
yamllint issue-templates/ # YAML 语法
定制(Gitea 客制化)
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;
与课程官网(https://cpp.tongji.sh/Website/)的互相导流见
customization/website-linkage.md。
详见各子目录的 README。
技术栈
| 组件 | 技术选型 |
|---|---|
| Git 平台 | Gitea(Docker 容器) |
| 数据库 | PostgreSQL 18(Docker 容器) |
| 服务器 | Rocky Linux 8.10 (aarch64) |
| 部署工具 | Docker Compose(见 deploy/) |
| 管理工具 | Python 3.14 + Typer + httpx + Pydantic + Dynaconf |
| 包管理 | uv |
| 测试框架 | pytest + respx + pytest-cov |
| 代码检查 | ruff, yamllint |
Languages
Python
55.9%
Shell
24.4%
Go Template
19.1%
Dockerfile
0.6%