Files
tjhlp-gitea/scripts/README.md
T
admin 9446850182
deploy / deploy (push) Successful in 25s
feat: Issue 发布者/回答者显示姓名, 而不是学号
Issue 页的作者名走 User.GetDisplayName(), 默认返回 login(学号),
看不到老师/助教认得的姓名。打开站点级开关 [ui] DEFAULT_SHOW_FULL_NAME
后改为显示 full_name, 未填姓名的用户回退学号。

配合 OIDC 侧把 full_name 覆盖成 display_name(学号-姓名), 即可同时
显示学号与姓名; 存量用户需重新登录才会刷新, 见 scripts/README.md。

- deploy/compose.yaml: GITEA__ui__DEFAULT_SHOW_FULL_NAME=true
- customization/preview/compose.yaml: 同步, 便于预览验证
- customization/README.md: 配置表 / 环境变量片段 / 已验证清单
- scripts/settings.toml: CLI 调 API 的地址改为宿主回环 127.0.0.1:2080
  (10.80.42.185:3000 未对外开放, 上层反代返回 502)

已在预览实例(Gitea 1.27.3)验证: 「由 X 创建」与正文/评论作者
均显示 full_name。
2026-09-25 19:04:24 +08:00

9.9 KiB

Python CLI 管理工具

tjhlp 是课程答疑平台的命令行管理工具, 通过 Gitea REST API 批量管理用户、组织、仓库、Webhook、Label, 并提供 Issue 统计和邮件通知功能。

前置要求

  • Python >= 3.14
  • uv

安装

cd scripts
uv sync

安装后即可使用 uv run tjhlp 调用。

配置

基础配置 (settings.toml)

已随项目提供, 包含默认值和预定义 Label 集合。一般无需修改。

敏感配置 (.secrets.toml)

cp .secrets.toml.example .secrets.toml

编辑 .secrets.toml, 填入实际值:

[default.gitea]
token = "your-gitea-api-token"    # 必填

API Token 获取方式: 登录 Gitea -> 设置 -> 应用 -> 生成令牌(勾选所有权限)。

.secrets.toml 已在 .gitignore 中排除, 不会被提交。

环境变量覆盖

所有配置项均可通过 TJHLP_ 前缀的环境变量覆盖:

export TJHLP_GITEA_URL=http://192.168.1.100:3000
export TJHLP_GITEA_TOKEN=your-token

命令一览

tjhlp
├── setup
│   ├── init              一键初始化: 创建组织/团队/仓库/Labels/Webhook
│   └── status            检查 Gitea 连接状态
├── users
│   ├── create            从 CSV 批量创建账号(随机密码)
│   ├── list              列出所有用户
│   └── delete            批量删除用户
├── orgs
│   ├── create            创建组织
│   ├── create-team       创建团队
│   ├── add-members       批量添加成员到团队
│   └── list-teams        列出组织下的团队
├── repos
│   ├── create            创建仓库
│   ├── create-homework   创建作业仓库(自动推送模板/Labels/Webhook)
│   ├── init-templates    推送 Issue Templates 到仓库
│   └── configure         配置仓库设置
├── webhooks
│   ├── create            创建 Webhook
│   ├── list              列出 Webhook
│   ├── test              测试 Webhook
│   └── delete            删除 Webhook
├── labels
│   ├── sync              同步预定义 Label 到仓库
│   └── list              列出仓库 Label
├── stats
│   ├── summary           Issue 统计摘要
│   └── export            导出 Issue 数据到 CSV
└── labels
    ├── sync              同步预定义 Label 到仓库
    └── list              列出仓库 Label

典型工作流

学期初始化

# 1. 检查连接
uv run tjhlp setup status

# 2. 一键初始化(创建组织 + 团队 + general 仓库 + Labels + Webhook)
uv run tjhlp setup init \
  --org tjhlp-2025f \
  --webhook-url http://notify-server:8080/webhook \
  --webhook-secret mysecret

# 3. 批量创建用户并分配到团队
uv run tjhlp users create --file members.csv --org tjhlp-2025f

典型工作流

学期初始化

# 1. 检查连接
uv run tjhlp setup status

# 2. 一键初始化(创建组织 + 团队 + general 仓库 + Labels + Webhook)
uv run tjhlp setup init \
  --org tjhlp-2025f \
  --webhook-url http://notify-server:8080/webhook \
  --webhook-secret mysecret

# 3. 批量创建用户并分配到团队
uv run tjhlp users create --file members.csv --org tjhlp-2025f

# 4. 发送账号密码邮件
uv run tjhlp notify send-credentials --file credentials_20250901_120000.csv

# 5. (可选)先预览邮件, 不实际发送
uv run tjhlp notify send-credentials --file credentials_*.csv --dry-run

每次布置作业

uv run tjhlp repos create-homework \
  --org tjhlp-2025f \
  --number 3 \
  --desc "作业3: 链表操作" \
  --webhook-url http://notify-server:8080/webhook

这会自动完成: 创建 hw03 仓库 -> 推送作业 Issue Template -> 同步 Labels -> 配置 Webhook -> 添加到 ta/students 团队。

日常管理

# 查看 Issue 统计
uv run tjhlp stats summary tjhlp-2025f/general

# 导出 Issue 数据
uv run tjhlp stats export tjhlp-2025f/hw03 --output hw03_issues.csv

# 同步 Label 到新仓库
uv run tjhlp labels sync tjhlp-2025f/hw03

# 查看 Webhook 状态
uv run tjhlp webhooks list tjhlp-2025f/general

显示名维护(学号-姓名)

Issue 页显示的是 full_name。OIDC 登录时会把 full_name 覆盖成认证源 FullNameClaimName 对应的 claim(display_name = 学号-姓名),因此存量用户 需要重新登录才会刷新。若不想等用户重登,用 tools/fix_full_name.py 直接刷一遍:

export TJHLP_GITEA_TOKEN=<token>        # 或建 scripts/.secrets.toml
uv run python tools/fix_full_name.py            # dry-run,只打印
uv run python tools/fix_full_name.py --apply    # 实际写入

脚本只改 full_name(成 学号-姓名),不动用户名/邮箱和团队归属;默认跳过 admin。

学期结束清理

uv run tjhlp users delete --file members.csv --yes

CSV 格式

输入: members.csv

id,name,role
2659999,赵一伤,student
2659876,钱二败,student
10001,李四催,ta
  • id - 学号或工号, 同时作为 Gitea 用户名
  • name - 姓名, 作为 Gitea 的 full_name
  • role - student 或 ta, 决定分配到哪个团队
  • 邮箱自动生成为 {id}@tongji.edu.cn
  • 初始密码与用户名(学号/工号)相同。

示例文件见 example/members.csv。

预定义 Label

通过 settings.toml 配置, setup init 和 labels sync 时自动创建:

Label 颜色 用途
duplicate 灰色 助教标记重复问题
invalid 黄色 不符合提问规范
resolved 绿色 已解决
wontfix 白色 不予处理
good-question 紫色 优质问题
FAQ 蓝色 常见问题
课程内容 粉紫 课程知识点相关
编程作业 浅红 编程作业相关
环境配置 浅青 环境配置相关
紧急 红色 需要尽快回复

测试

安装开发依赖

uv sync --extra dev

运行测试

uv run pytest tests/ -v              # 全部测试
uv run pytest tests/test_models.py   # 只运行模型测试
uv run pytest tests/ -k "password"   # 按名称过滤

覆盖率报告

uv run pytest tests/ --cov=tjhlp --cov-report=term-missing

代码检查

uv run ruff check src/
uv run ruff format --check src/

测试套件结构

tests/
├── conftest.py              公共 fixtures(mock config、client、样本数据)
├── test_models.py           数据模型(MemberRecord、Gitea API 模型、枚举)
├── test_config.py           配置校验(LabelDef 颜色、GiteaConfig 必填字段)
├── test_utils.py            工具函数(parse_repo、compute_issue_stats)
├── test_client.py           API 客户端(respx mock HTTP, 分页、错误处理、CRUD)
└── test_commands.py         命令集成(CliRunner + mock, setup/users/repos 流程)

测试分层

层级 测试对象 方法 速度
单元测试 models, config, 纯函数 直接调用, 无 mock 极快
API 客户端测试 client.py respx mock HTTP 层 快
命令集成测试 commands/*.py Typer CliRunner + mock GiteaClient 快
端到端测试 完整流程 需要运行中的 Gitea 实例 慢(手动)

当前 93 个测试用例, 核心模块覆盖率:

模块 覆盖率 说明
models.py 100% 全部模型和 computed fields
config.py 87% Pydantic 校验逻辑(未覆盖 Dynaconf 加载函数)
users.py 79% 创建/跳过/删除流程
client.py 67% 核心 HTTP 方法和分页(未覆盖所有 API endpoint)

项目结构

scripts/
├── pyproject.toml              项目配置(Python >=3.14, 依赖声明)
├── settings.toml               默认配置 + 预定义 Label
├── .secrets.toml.example       敏感配置示例
├── example/
│   └── members.csv             示例成员名单
├── tests/                      测试套件
│   ├── conftest.py             公共 fixtures
│   ├── test_models.py          数据模型测试
│   ├── test_config.py          配置校验测试
│   ├── test_utils.py           工具函数测试
│   ├── test_pure_functions.py  纯函数测试
│   ├── test_client.py          API 客户端测试
│   └── test_commands.py        命令集成测试
└── src/tjhlp/
    ├── cli.py                  Typer 主入口
    ├── config.py               Dynaconf 加载 + Pydantic 校验
    ├── client.py               Gitea REST API 客户端(自动分页/错误处理)
    ├── models.py               数据模型
    ├── utils.py                共享工具函数(parse_repo, push_templates 等)
    └── commands/
        ├── setup.py            初始化命令
        ├── users.py            用户管理
        ├── orgs.py             组织/团队管理
        ├── repos.py            仓库管理
        ├── webhooks.py         Webhook 管理
        ├── labels.py           Label 管理
        └── stats.py            Issue 统计

技术选型

库 用途
Typer CLI 框架
httpx HTTP 客户端(调用 Gitea API)
Rich 终端美化(表格、颜色、进度)
Pydantic 数据校验、配置模型
Dynaconf 配置管理(TOML + 环境变量 + secrets 分离)
pytest 测试框架
respx httpx mock 库(API 客户端测试)
ruff 代码检查与格式化