SHA256
forked from course-team/tjhlp-gitea
登录后首页原本是贡献热力图/最近活动/仓库列表, 对只来提问的同学是干扰。
现在 navbar 之下、热力图之上插一张约 1/3 屏高(33vh)的卡片, 里面一个按钮直达
本学期答疑区, 顺带给出「提问指南」和官网《学会提问》的入口。
实现:
- custom/templates/user/dashboard/dashboard.tmpl: 覆盖上游同名模板,
只比上游多一行 {{template "custom/tjhlp_semester_card" .}}(便于升级时 diff)
- custom/templates/custom/tjhlp_semester_card.tmpl: 卡片本体(自己写的), 规则:
* 数据来自 .Orgs(当前用户所属组织)
* 学期组织 = 名字形如 tjhlp-<5 位数字>; 26271 => 26|27|1 => 2026-2027 学年第一学期
旧命名 tjhlp-2026s(带字母)、course-team 之类都不认
* 同时匹配多个取最新(名字最大), 按钮指向 <学期组织>/general/issues
* 一个都不匹配 => 整张卡片不显示
判定/文案都在这个文件里, 不依赖 Tailwind 工具类(用行内样式), 升级影响面最小
预览侧:
- preview.sh 新增 semester: 造学期组织 + general 仓库(幂等), 用于看卡片
- preview.sh check 增加登录后的断言(卡片存在 / 按钮链接 / 33vh), 现 17 项全过
预览里实测三个用户: previewadmin(在 26271/25261/2026s 三个组织里) -> 26271,
student1(只在 27282) -> 27282, student2(无组织) -> 不显示卡片且页面正常
148 lines
4.8 KiB
Markdown
148 lines
4.8 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)
|
|
├── 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);
|
|
与课程官网(<https://cpp.tongji.sh/Website/>)的互相导流见
|
|
[`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 |
|