# 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) ├── customization/ Gitea 客制化(首页、中文术语、去 Gitea 化)与本地预览 ├── 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 语法 ``` ### 定制(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); 与课程官网()的互相导流见 [`customization/website-linkage.md`](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 |