Files
tjhlp-gitea/README.md
T
admin 79256c5be0 feat: 新增 Docker Compose 部署方案, 移除未验证的 ansible 草案
原 ansible/ 方案从未在任何环境验证过, 且与本机实际状态严重不符(硬编码
amd64 二进制、会覆盖生产 /etc/gitea/app.ini、会启动 firewalld 切断其它
服务、建的库名与现网不一致); 加上宿主机 Rocky 8 的系统 Python 无法升级,
新版 ansible 也跑不起来。改为 Docker Compose。

新增 deploy/:
- compose.yaml    版本锁定; Gitea 只发布 127.0.0.1:2080(Apache 反代无需
                  改动), PostgreSQL 不发布端口; 配置全部由
                  GITEA__section__KEY 环境变量注入; 数据用 bind mount
- db/Dockerfile   官方 postgres 只生成 en_US.UTF-8, 这里补 zh_CN.UTF-8,
                  与现有集群 collation 保持一致
- scripts/        backup.sh(pg_dump + 数据 tar + SHA256SUMS)、
                  restore.sh(默认 dry-run, 校验后还原, 拒收宿主布局备份)、
                  verify.sh(容器健康 + 回环 API + 经 Apache 反代)

文档 deploy/README.md 以 部署/备份/恢复/升级 四条流程为主线, 并记录本机
踩过的四个陷阱: PG18 挂载点、s6 chown 守卫、APP_NAME 只能走裸变量、
HTTP 代理导致的假 502。

一次性迁移脚本(install-docker / configure-docker-proxy / preflight /
migrate-from-binary)已清理, 相应步骤内联进文档。

实测: 源 116 表 → 目标 116 表, /api/healthz 200, 经 Apache /QA 200,
站点名与 OIDC 登录源注册正常。
2026-09-11 16:00:15 +08:00

133 lines
4.0 KiB
Markdown

# TJHLP-Gitea
同济大学高级语言程序设计课程(Tongji High-level Language Programming)基于 Gitea 的答疑平台。
## 项目背景
为课程搭建自托管的 Git 答疑平台, 提供以下能力:
- 学生通过 Issue 提问, 结构化的 Issue Template 引导提问前思考、规范问题描述
- 助教通过 Label 标记重复 / 低质问题, 管理答疑流程
- Webhook 将 Issue 动态推送到 IM(如 QQ 机器人), 助教无需轮询平台即可收到通知
- Python CLI 工具批量管理用户、仓库、标签等, 降低运维负担
选择 Gitea 自托管而非 GitHub Classroom / Piazza 等方案, 是因为国内网络环境限制, 且需要定制化功能。
## 项目结构
```text
tjhlp-gitea/
├── deploy/ Docker 部署与运维(Gitea + PostgreSQL)
├── issue-templates/ Issue 模板(按仓库类型区分)
└── scripts/ Python CLI 管理工具
```
## 快速开始
### 1. 部署服务器
需要一台 Rocky Linux 8.10 服务器, 以及 Docker(含 compose 插件)。
```bash
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`](deploy/README.md)。
### 2. 初始化平台
登录管理员账号, 在 **设置 -> 应用** 中创建 API Token, 然后:
```bash
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`):
```csv
id,name,role
2659999,赵一伤,student
10001,李四催,ta
```
```bash
uv run tjhlp users create --file members.csv --org tjhlp-2025f
uv run tjhlp notify send-credentials --file credentials_*.csv
```
### 4. 创建作业仓库
```bash
uv run tjhlp repos create-homework --org tjhlp-2025f --number 1
```
## 仓库设计
| 仓库 | 用途 | Issue Template |
| ------ | ------ | ---------------- |
| `{org}/general` | 一般性问题: 课程内容答疑、环境配置 | 课程答疑 / 作业问题 / 环境配置 |
| `{org}/hw01` ... | 各次作业的特定问题 | 仅作业问题模板 |
## 开发与测试
### Python CLI 测试
```bash
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](https://lundberg.github.io/respx/) mock HTTP 层, 测试分页、错误处理、404 返回 None
- **命令集成**— 使用 Typer CliRunner + mock 测试 setup/users/repos 命令的完整流程
### 部署配置检查
```bash
cd deploy
docker compose config --quiet # 校验 compose 与 .env 插值
sudo ./scripts/verify.sh # 部署后验证(容器健康 + API + 反代)
./scripts/restore.sh --list # 查看可用备份及校验状态
```
### Issue Templates 验证
```bash
yamllint issue-templates/ # YAML 语法
```
详见各子目录的 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 |