jkljkluiouio e94b5f1398 feat(deploy): 添加 Docker Compose 部署方案
新增 Docker Compose 部署方式,包含 Gitea 和 PostgreSQL 容器化配置
更新 README 文档说明两种部署方式
添加 .env 示例文件和 docker-compose.yml 配置文件

Signed-off-by: oierxjn <[email protected]>
2026-04-22 21:46:55 +08:00
2026-04-12 23:24:13 +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/
├── ansible/            Ansible 自动化部署(Gitea + PostgreSQL)
├── deploy/             测试使用的部署方案(如 Docker Compose)
├── issue-templates/    Issue 模板(按仓库类型区分)
└── scripts/            Python CLI 管理工具

快速开始

1. 选择部署方式

本项目当前提供两种并行的单机部署方式:

  • Ansible: 现有正式方案, 面向 Rocky Linux 8.10 主机, 直接安装 Gitea 二进制 + PostgreSQL + systemd
  • Docker Compose: 测试方案, 面向单机容器部署, 默认只包含 Gitea + PostgreSQL, 反向代理/TLS 由外部处理

如果你使用 Docker Compose, 先参考 deploy/compose/README.md 完成服务启动, 然后再回到下面的“初始化平台”步骤。

2. 使用 Ansible 部署服务器

需要一台 Rocky Linux 8.10 服务器和本地安装的 Ansible。

cd ansible
cp inventory/hosts.yml.example inventory/hosts.yml
cp inventory/group_vars/all.yml.example inventory/group_vars/all.yml

编辑 ansible/inventory/hosts.yml 填入服务器地址
编辑 ansible/inventory/group_vars/all.yml 修改域名、密码等

ansible-playbook playbook.yml

部署完成后, Ansible 会自动创建管理员账号并输出访问地址。

3. 初始化平台

登录管理员账号, 在 设置 -> 应用 中创建 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。

4. 导入用户

准备 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

5. 创建作业仓库

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 命令的完整流程

Ansible 静态检查

cd ansible
ansible-playbook --syntax-check playbook.yml     # 语法检查
yamllint -c .yamllint.yml .                       # YAML 格式
ansible-lint playbook.yml                         # 最佳实践

Issue Templates 验证

yamllint issue-templates/                         # YAML 语法

详见各子目录的 README。

技术栈

组件 技术选型
Git 平台 Gitea(二进制 + systemd)
数据库 PostgreSQL 18
服务器 Rocky Linux 8.10
部署工具 Ansible / Docker Compose
管理工具 Python 3.14 + Typer + httpx + Pydantic + Dynaconf
包管理 uv
测试框架 pytest + respx + pytest-cov
代码检查 ruff, yamllint, ansible-lint
S
Description
No description provided
Readme
180 KiB
Languages
Python 93.9%
Jinja 3.1%
Shell 3%