admin 73ce8162aa
deploy / deploy (push) Skipped
feat(ci): 落地 main 自动部署的可复用件(runner 配置/部署脚本/定制断言/工作流)
按 deploy/ci-cd.md 方案把除推送触发之外的东西都准备好:

- customization/check.sh <base-url>: 把 preview.sh check 里的"定制生效"断言抽成
  任意实例可跑的脚本(首页/页脚/meta/官网链接/登录页两张卡/无通行密钥方框/
  无「工单」/无 example.com), 另加生产才有的 OIDC 入口 307 断言(404 = 认证源没注册上)。
  实测对生产 17/17 通过。
- deploy/scripts/auto-deploy.sh: build.py -> compose up -d -> verify.sh + check.sh,
  失败自动回滚到 deploy/.state/last-deployed; flock 串行; 结束时把 clone 所有权还给
  ymy(job 容器里是 root); 内网验证强制不走代理。
- deploy/runner/{compose.yaml,config.yaml,.env.example}: act_runner v0.6.1 跑在容器里
  (不需要 root), network: host + 同路径挂载部署克隆 + 宿主 docker CLI/compose 插件,
  capacity 1 保证部署串行。
- .gitea/workflows/deploy.yml: push main + workflow_dispatch, [skip deploy] 跳过,
  concurrency 串行, 只做"同步到 github.sha + 调 auto-deploy.sh"。
- .gitignore: deploy/.state/、deploy/runner/{.env,data/}。

依据见 deploy/ci-cd.md(含全部实测证据与待确认项)。
2026-09-13 22:09:32 +08:00

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 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
S
Description
No description provided
Readme
801 KiB
Languages
Python 55.9%
Shell 24.4%
Go Template 19.1%
Dockerfile 0.6%