7 Commits
Author SHA256 Message Date
jkljkluiouio e96960c539 fix(测试): 改进用户创建测试并添加凭据导出验证
- 在测试中增加对凭据导出的验证
- 使用更安全的随机密码生成
- 添加对创建失败情况的测试覆盖
- 更新文档中的测试命令以包含临时目录参数
- 将临时测试目录添加到.gitignore
2026-04-29 13:44:00 +08:00
jkljkluiouio b8220a97c4 feat(users): 为用户创建命令添加随机密码生成和凭据导出功能
- 将初始密码从固定用户名改为随机生成
- 添加 CredentialRecord 数据结构记录创建结果
- 实现凭据 CSV 自动导出功能
- 更新相关文档说明
2026-04-29 13:44:00 +08:00
jkljkluiouio 7427bfe132 docs: 更新README文档内容' (#4)
- 移除邮件通知功能相关描述
- 修正用户创建时的密码策略说明
- 优化文档结构,删除重复内容
- 添加cmd环境下的命令示例
- 更新测试文件列表
2026-04-29 13:32:36 +08:00
jkljkluiouio 20d6d7eef5 docs: 更新README文档内容
- 移除邮件通知功能相关描述
- 修正用户创建时的密码策略说明
- 优化文档结构,删除重复内容
- 添加cmd环境下的命令示例
- 更新测试文件列表
2026-04-23 22:43:22 +08:00
jkljkluiouio 45dc819fda docker: 添加使用docker部署的方法用于快速测试 (#2)
添加使用docker部署的方法**用于快速测试**
路径于`deploy\compose`,目录下有相应部署指导文档

本次改动还将一些配置置为 example,在 git 中取消追踪**以免误操作将敏感信息提交**

Reviewed-on: https://cpp.tongji.sh:2080/jkljkluiouio/tjhlp-gitea/pulls/2
Co-authored-by: oierxjn <[email protected]>
Co-committed-by: oierxjn <[email protected]>
2026-04-23 22:20:52 +08:00
jkljkluiouio c338d39ed4 Merge pull request 'chore(ansible): 停止Git追踪服务器相关配置文件,改为添加示例配置文件' (#1) from chore/ansible into main
Reviewed-on: https://cpp.tongji.sh:2080/jkljkluiouio/tjhlp-gitea/pulls/1
2026-04-22 19:52:50 +08:00
jkljkluiouio 25c1fa9bd7 chore(ansible): 停止Git追踪服务器相关配置文件,改为添加示例配置文件
添加hosts.yml和all.yml的示例配置文件
更新README.md中的部署说明
将敏感配置文件添加到.gitignore
2026-04-21 15:16:46 +08:00
12 changed files with 613 additions and 63 deletions
+7
View File
@@ -33,3 +33,10 @@ Thumbs.db
# OpenCode # OpenCode
.opencode/ .opencode/
# Server inventory
ansible/inventory/hosts.yml
ansible/inventory/group_vars/all.yml
# Docker Compose local config
deploy/compose/.env
+25 -9
View File
@@ -18,26 +18,42 @@
```text ```text
tjhlp-gitea/ tjhlp-gitea/
├── ansible/ Ansible 自动化部署(Gitea + PostgreSQL) ├── ansible/ Ansible 自动化部署(Gitea + PostgreSQL)
├── deploy/ 测试使用的部署方案(如 Docker Compose)
├── issue-templates/ Issue 模板(按仓库类型区分) ├── issue-templates/ Issue 模板(按仓库类型区分)
└── scripts/ Python CLI 管理工具 └── scripts/ Python CLI 管理工具
``` ```
## 快速开始 ## 快速开始
### 1. 部署服务器 ### 1. 选择部署方式
本项目当前提供两种并行的单机部署方式:
- **Ansible**: 现有正式方案, 面向 Rocky Linux 8.10 主机, 直接安装 Gitea 二进制 + PostgreSQL + systemd
- **Docker Compose**: 测试方案, 面向单机容器部署, 默认只包含 Gitea + PostgreSQL, 提供管理员初始化脚本, 反向代理/TLS 由外部处理
如果你使用 Docker Compose, 先参考 [deploy/compose/README.md](deploy/compose/README.md) 完成服务启动, 然后再回到下面的“初始化平台”步骤。
### 2. 使用 Ansible 部署服务器
需要一台 Rocky Linux 8.10 服务器和本地安装的 Ansible。 需要一台 Rocky Linux 8.10 服务器和本地安装的 Ansible。
```bash ```bash
cd ansible cd ansible
# 编辑 inventory/hosts.yml 填入服务器地址 cp inventory/hosts.yml.example inventory/hosts.yml
# 编辑 inventory/group_vars/all.yml 修改域名、密码等 cp inventory/group_vars/all.yml.example inventory/group_vars/all.yml
```
编辑 ansible/inventory/hosts.yml 填入服务器地址
编辑 ansible/inventory/group_vars/all.yml 修改域名、密码等
```bash
ansible-playbook playbook.yml ansible-playbook playbook.yml
``` ```
部署完成后, Ansible 会自动创建管理员账号并输出访问地址。 部署完成后, Ansible 会自动创建管理员账号并输出访问地址。
### 2. 初始化平台 ### 3. 初始化平台
登录管理员账号, 在 **设置 -> 应用** 中创建 API Token, 然后: 登录管理员账号, 在 **设置 -> 应用** 中创建 API Token, 然后:
@@ -52,7 +68,7 @@ uv run tjhlp setup init --org tjhlp-2025f
这会创建课程组织、ta/students 团队、general 答疑仓库, 并推送 Issue Template 和预定义 Label。 这会创建课程组织、ta/students 团队、general 答疑仓库, 并推送 Issue Template 和预定义 Label。
### 3. 导入用户 ### 4. 导入用户
准备 CSV 文件(格式见 `scripts/example/members.csv`): 准备 CSV 文件(格式见 `scripts/example/members.csv`):
@@ -67,7 +83,7 @@ uv run tjhlp users create --file members.csv --org tjhlp-2025f
uv run tjhlp notify send-credentials --file credentials_*.csv uv run tjhlp notify send-credentials --file credentials_*.csv
``` ```
### 4. 创建作业仓库 ### 5. 创建作业仓库
```bash ```bash
uv run tjhlp repos create-homework --org tjhlp-2025f --number 1 uv run tjhlp repos create-homework --org tjhlp-2025f --number 1
@@ -87,8 +103,8 @@ uv run tjhlp repos create-homework --org tjhlp-2025f --number 1
```bash ```bash
cd scripts cd scripts
uv sync --extra dev uv sync --extra dev
uv run pytest tests/ -v # 运行全部测试 uv run pytest tests/ -v --basetemp .pytest_tmp # 运行全部测试
uv run pytest tests/ --cov=tjhlp --cov-report=term-missing # 带覆盖率 uv run pytest tests/ --cov=tjhlp --cov-report=term-missing --basetemp .pytest_tmp # 带覆盖率
``` ```
当前测试套件包含 99 个测试用例, 覆盖: 当前测试套件包含 99 个测试用例, 覆盖:
@@ -123,7 +139,7 @@ yamllint issue-templates/ # YAML 语法
| Git 平台 | Gitea(二进制 + systemd) | | Git 平台 | Gitea(二进制 + systemd) |
| 数据库 | PostgreSQL 18 | | 数据库 | PostgreSQL 18 |
| 服务器 | Rocky Linux 8.10 | | 服务器 | Rocky Linux 8.10 |
| 部署工具 | Ansible | | 部署工具 | Ansible / Docker Compose |
| 管理工具 | Python 3.14 + Typer + httpx + Pydantic + Dynaconf | | 管理工具 | Python 3.14 + Typer + httpx + Pydantic + Dynaconf |
| 包管理 | uv | | 包管理 | uv |
| 测试框架 | pytest + respx + pytest-cov | | 测试框架 | pytest + respx + pytest-cov |
@@ -0,0 +1,42 @@
---
# =============================================================================
# Gitea 答疑平台部署变量
# =============================================================================
# -----------------------------------------------------------------------------
# Gitea 基础配置
# -----------------------------------------------------------------------------
# 留空则自动获取最新版本, 填写则使用指定版本(如 "1.25.1")
gitea_version: ""
gitea_http_port: 3000
gitea_domain: "gitea.example.com" # 替换为实际域名或 IP
gitea_app_name: "同济大学高级语言程序设计答疑平台"
# -----------------------------------------------------------------------------
# Gitea 管理员账号(首次部署自动创建, 部署后请修改密码)
# -----------------------------------------------------------------------------
gitea_admin_user: "admin"
gitea_admin_password: "ChangeMe!2026" # 部署后务必修改
gitea_admin_email: "[email protected]"
# -----------------------------------------------------------------------------
# PostgreSQL 数据库配置
# -----------------------------------------------------------------------------
postgresql_version: 18
gitea_db_name: "gitea"
gitea_db_user: "gitea"
gitea_db_password: "change_this_db_password" # 请修改为强密码
# -----------------------------------------------------------------------------
# Webhook 配置
# -----------------------------------------------------------------------------
gitea_webhook_allowed_hosts: "*"
gitea_webhook_skip_tls: "false"
# -----------------------------------------------------------------------------
# 安全密钥(留空则自动生成, 生成后建议记录保存)
# -----------------------------------------------------------------------------
gitea_secret_key: ""
gitea_internal_token: ""
gitea_lfs_jwt_secret: ""
+7
View File
@@ -0,0 +1,7 @@
---
all:
hosts:
gitea-server:
ansible_host: 192.168.1.100 # 替换为实际服务器 IP
ansible_user: root # 替换为实际 SSH 用户
# ansible_ssh_private_key_file: ~/.ssh/id_rsa
+28
View File
@@ -0,0 +1,28 @@
# Copy this file to .env before running docker compose.
# Image versions
GITEA_IMAGE=gitea/gitea:1.24.7
POSTGRES_IMAGE=postgres:18
# Container runtime user
PUID=1000
PGID=1000
# Published ports on the Docker host
GITEA_HTTP_PORT=3000
# Public URL used by Gitea
# For local access you can keep localhost.
GITEA_DOMAIN=localhost
GITEA_ROOT_URL=http://localhost:3000/
# PostgreSQL settings
POSTGRES_DB=gitea
POSTGRES_USER=gitea
POSTGRES_PASSWORD=change_this_db_password
POSTGRES_SSL_MODE=disable
# First admin account used by init-admin.sh
GITEA_ADMIN_USERNAME=admin
GITEA_ADMIN_PASSWORD=ChangeMe!2026
GITEA_ADMIN_EMAIL=[email protected]
+140
View File
@@ -0,0 +1,140 @@
# Docker Compose 部署
- 目标: 单机容器部署 `Gitea + PostgreSQL`
- 不包含: Nginx、TLS 证书、外部对象存储、多节点编排
- 上层使用方式不变: 服务启动后仍然使用 `scripts/` 里的 `tjhlp` CLI 初始化课程组织、仓库、标签和 Webhook
## 文件说明
- `docker-compose.yml`: 启动 Gitea 与 PostgreSQL
- `.env.example`: 本地变量模板, 复制为 `.env` 后修改
- `init-admin.sh`: 读取 `.env` 中的管理员参数并初始化首个管理员账号
## 前置要求
- 已安装 Docker Engine
- 已安装 Docker Compose Plugin, 能执行 `docker compose`
- 目标机器开放 Gitea HTTP 访问端口
## 快速开始
```bash
cd deploy/compose
sudo cp .env.example .env
```
编辑 `.env`, 至少确认这些变量:
- `GITEA_IMAGE` / `POSTGRES_IMAGE`: 要使用的镜像版本
- `GITEA_ROOT_URL`: Gitea 对外访问地址, 必须与实际访问 URL 一致
- `GITEA_DOMAIN`: 对外访问域名或主机名
- `GITEA_HTTP_PORT`: 宿主机暴露的 Gitea 端口
- `POSTGRES_PASSWORD`: PostgreSQL 密码
- `PUID` / `PGID`: 容器内 Gitea 运行用户的 UID/GID, 默认 1000
- `GITEA_ADMIN_USERNAME`
- `GITEA_ADMIN_PASSWORD`
- `GITEA_ADMIN_EMAIL`
启动服务:
```bash
sudo docker compose up -d
sudo docker compose logs -f gitea
```
首次启动后, 运行管理员初始化脚本:
```bash
sudo sh ./init-admin.sh
```
脚本会:
- 从 `.env` 读取 `GITEA_ADMIN_USERNAME`、`GITEA_ADMIN_PASSWORD`、`GITEA_ADMIN_EMAIL`
- 等待 Gitea API 就绪
- 首次运行时创建管理员
- 再次运行时若管理员已存在则直接跳过
创建完成后, 访问 `GITEA_ROOT_URL`, 用 `.env` 中配置的管理员账号登录。
(不推荐Windows)如果你在 Windows 上使用 Docker Desktop, 建议通过 Git Bash 或 WSL 执行 `init-admin.sh`。
## 课程平台初始化
1. 登录 Gitea
2. 在“设置 -> 应用”中创建 API Token
3. 进入仓库 `scripts/` 目录
4. 配置 `.secrets.toml`
5. 执行:
```bash
uv sync
uv run tjhlp setup status
uv run tjhlp setup init --org tjhlp-2025f
```
如果是 Docker Compose 部署, 记得把 `scripts/settings.toml` 或环境变量中的 Gitea URL 指向 `GITEA_ROOT_URL`。
例如:
```bash
export TJHLP_GITEA_URL=http://localhost:3000
```
PowerShell:
```powershell
$env:TJHLP_GITEA_URL = "http://localhost:3000"
```
## 常用命令
启动:
```bash
sudo docker compose up -d
```
停止:
```bash
sudo docker compose down
```
查看日志:
```bash
sudo docker compose logs -f gitea
sudo docker compose logs -f postgres
```
升级镜像:
```bash
sudo docker compose pull
sudo docker compose up -d
```
## 数据持久化
本方案使用 Docker 命名卷:
- `gitea_data`: Gitea 仓库、附件、LFS、配置等数据
- `postgres_data`: PostgreSQL 数据目录
删除容器不会删除卷, 但执行带 `--volumes` 的 `docker compose down` 会清空数据。
## 与 Ansible 方案的关系
- `ansible/` 仍然是现有的主机直装方案
- `deploy/compose/` 是新增的单机容器方案
- 两者部署完成后, 上层 `scripts/` 的初始化和日常管理方式一致
## 注意事项
- `.env` 放环境差异和敏感参数, `docker-compose.yml` 保留项目默认策略配置
- 该方案默认只暴露 HTTP, 若要对外提供 HTTPS, 请在外部使用 Nginx/Caddy 等反向代理
- `GITEA_ROOT_URL` 配错时, Web 界面跳转、Webhook 和仓库链接通常会异常
- 如果宿主机已经占用 `3000`, 请调整 `.env` 中的端口映射
- PostgreSQL 默认不对宿主机暴露端口, 以减少额外暴露面
+49
View File
@@ -0,0 +1,49 @@
services:
postgres:
image: ${POSTGRES_IMAGE}
container_name: tjhlp-postgres
restart: unless-stopped
environment:
POSTGRES_DB: ${POSTGRES_DB}
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
volumes:
- postgres_data:/var/lib/postgresql
gitea:
image: ${GITEA_IMAGE}
container_name: tjhlp-gitea
restart: unless-stopped
depends_on:
- postgres
environment:
USER_UID: ${PUID}
USER_GID: ${PGID}
GITEA__database__DB_TYPE: postgres
GITEA__database__HOST: postgres:5432
GITEA__database__NAME: ${POSTGRES_DB}
GITEA__database__USER: ${POSTGRES_USER}
GITEA__database__PASSWD: ${POSTGRES_PASSWORD}
GITEA__database__SSL_MODE: ${POSTGRES_SSL_MODE}
GITEA__server__DOMAIN: ${GITEA_DOMAIN}
GITEA__server__HTTP_PORT: ${GITEA_HTTP_PORT}
GITEA__server__ROOT_URL: ${GITEA_ROOT_URL}
GITEA__server__LFS_START_SERVER: "true"
GITEA__repository__DEFAULT_BRANCH: main
GITEA__repository__DEFAULT_REPO_UNITS: repo.code,repo.issues
GITEA__security__INSTALL_LOCK: "true"
GITEA__service__DISABLE_REGISTRATION: "true"
GITEA__service__REQUIRE_SIGNIN_VIEW: "false"
GITEA__mailer__ENABLED: "false"
GITEA__webhook__ALLOWED_HOST_LIST: "*"
GITEA__webhook__SKIP_TLS_VERIFY: "false"
GITEA__api__ENABLE_SWAGGER: "true"
GITEA__api__MAX_RESPONSE_ITEMS: "100"
ports:
- "${GITEA_HTTP_PORT}:${GITEA_HTTP_PORT}"
volumes:
- gitea_data:/data
volumes:
postgres_data:
gitea_data:
+101
View File
@@ -0,0 +1,101 @@
#!/usr/bin/env sh
set -eu
SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
ENV_FILE="$SCRIPT_DIR/.env"
COMPOSE_FILE="$SCRIPT_DIR/docker-compose.yml"
log() {
printf '%s\n' "$*"
}
fail() {
printf 'Error: %s\n' "$*" >&2
exit 1
}
require_command() {
command -v "$1" >/dev/null 2>&1 || fail "missing required command: $1"
}
require_command docker
[ -f "$COMPOSE_FILE" ] || fail "docker-compose.yml not found in $SCRIPT_DIR"
[ -f "$ENV_FILE" ] || fail ".env not found in $SCRIPT_DIR; copy .env.example to .env first"
set -a
# shellcheck disable=SC1090
. "$ENV_FILE"
set +a
for var_name in GITEA_ADMIN_USERNAME GITEA_ADMIN_PASSWORD GITEA_ADMIN_EMAIL GITEA_ROOT_URL GITEA_HTTP_PORT PUID PGID; do
# 固定列表,非用户输入,无注入风险
eval "var_value=\${$var_name:-}"
[ -n "$var_value" ] || fail "required variable $var_name is missing or empty in .env"
done
dc() {
docker compose --file "$COMPOSE_FILE" --env-file "$ENV_FILE" "$@"
}
check_gitea_ready() {
dc exec -T gitea sh -c "
if command -v wget >/dev/null 2>&1; then
wget -q -O - 'http://127.0.0.1:${GITEA_HTTP_PORT}/api/v1/version' >/dev/null 2>&1
elif command -v curl >/dev/null 2>&1; then
curl -fsS 'http://127.0.0.1:${GITEA_HTTP_PORT}/api/v1/version' >/dev/null 2>&1
else
exit 1
fi
"
}
dc version >/dev/null 2>&1 || fail "docker compose is not available"
gitea_state=$(dc ps -q gitea 2>/dev/null || true)
[ -n "$gitea_state" ] || fail "gitea service is not created; run 'docker compose up -d' first"
db_state=$(dc ps -q postgres 2>/dev/null || true)
[ -n "$db_state" ] || fail "postgres service is not created; run 'docker compose up -d' first"
log "Waiting for Gitea to become ready at ${GITEA_ROOT_URL%/}/api/v1/version ..."
attempt=0
max_attempts=30
ready=0
# 最长约 60 秒,每 2 秒检查一次
while [ "$attempt" -lt "$max_attempts" ]; do
attempt=$((attempt + 1))
if check_gitea_ready; then
ready=1
break
fi
sleep 2
done
[ "$ready" -eq 1 ] || fail "Gitea did not become ready after $((max_attempts * 2)) seconds"
log "Creating admin user '${GITEA_ADMIN_USERNAME}' if needed ..."
create_output=$(
dc exec -T --user "${PUID}:${PGID}" gitea gitea admin user create \
--admin \
--username "$GITEA_ADMIN_USERNAME" \
--password "$GITEA_ADMIN_PASSWORD" \
--email "$GITEA_ADMIN_EMAIL" 2>&1
) || {
case "$create_output" in
*"already exists"*)
log "Admin user '${GITEA_ADMIN_USERNAME}' already exists; skipping."
exit 0
;;
*)
printf '%s\n' "$create_output" >&2
fail "failed to create admin user"
;;
esac
}
log "Admin user '${GITEA_ADMIN_USERNAME}' created successfully."
+1
View File
@@ -9,6 +9,7 @@ build/
*.egg *.egg
# Pytest # Pytest
.pytest_tmp/
.coverage .coverage
# Secrets & credentials # Secrets & credentials
+21 -34
View File
@@ -1,6 +1,6 @@
# Python CLI 管理工具 # Python CLI 管理工具
`tjhlp` 是课程答疑平台的命令行管理工具, 通过 Gitea REST API 批量管理用户、组织、仓库、Webhook、Label, 并提供 Issue 统计和邮件通知功能。 `tjhlp` 是课程答疑平台的命令行管理工具, 通过 Gitea REST API 批量管理用户、组织、仓库、Webhook、Label, 并提供 Issue 统计功能。
## 前置要求 ## 前置要求
@@ -56,7 +56,7 @@ tjhlp
│ ├── init 一键初始化: 创建组织/团队/仓库/Labels/Webhook │ ├── init 一键初始化: 创建组织/团队/仓库/Labels/Webhook
│ └── status 检查 Gitea 连接状态 │ └── status 检查 Gitea 连接状态
├── users ├── users
│ ├── create 从 CSV 批量创建账号(随机密码) │ ├── create 从 CSV 批量创建账号(随机初始密码, 自动导出凭据 CSV)
│ ├── list 列出所有用户 │ ├── list 列出所有用户
│ └── delete 批量删除用户 │ └── delete 批量删除用户
├── orgs ├── orgs
@@ -77,12 +77,9 @@ tjhlp
├── labels ├── labels
│ ├── sync 同步预定义 Label 到仓库 │ ├── sync 同步预定义 Label 到仓库
│ └── list 列出仓库 Label │ └── list 列出仓库 Label
├── stats └── stats
│ ├── summary Issue 统计摘要 ├── summary Issue 统计摘要
│ └── export 导出 Issue 数据到 CSV └── export 导出 Issue 数据到 CSV
└── labels
├── sync 同步预定义 Label 到仓库
└── list 列出仓库 Label
``` ```
## 典型工作流 ## 典型工作流
@@ -103,29 +100,14 @@ uv run tjhlp setup init \
uv run tjhlp users create --file members.csv --org tjhlp-2025f uv run tjhlp users create --file members.csv --org tjhlp-2025f
``` ```
执行完成后会自动生成 `credentials_YYYYMMDD_HHMMSS.csv`, 包含账号、随机初始密码和处理状态。
## 典型工作流 `cmd` 可直接复制的写法:
### 学期初始化 ```cmd
```bash
# 1. 检查连接
uv run tjhlp setup status uv run tjhlp setup status
uv run tjhlp setup init --org tjhlp-2025f --webhook-url http://notify-server:8080/webhook --webhook-secret mysecret
# 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 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
``` ```
### 每次布置作业 ### 每次布置作业
@@ -138,6 +120,12 @@ uv run tjhlp repos create-homework \
--webhook-url http://notify-server:8080/webhook --webhook-url http://notify-server:8080/webhook
``` ```
`cmd` 可直接复制的写法:
```cmd
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 团队。 这会自动完成: 创建 `hw03` 仓库 -> 推送作业 Issue Template -> 同步 Labels -> 配置 Webhook -> 添加到 ta/students 团队。
### 日常管理 ### 日常管理
@@ -174,10 +162,10 @@ id,name,role
``` ```
- `id` - 学号或工号, 同时作为 Gitea 用户名 - `id` - 学号或工号, 同时作为 Gitea 用户名
- `name` - 姓名, 作为 Gitea 的 full_name - `name` - 姓名, 作为 Gitea 的 `full_name`
- `role` - `student` 或 `ta`, 决定分配到哪个团队 - `role` - `student` 或 `ta`, 决定分配到哪个团队
- 邮箱自动生成为 `{id}@tongji.edu.cn` - 邮箱自动生成为 `{id}@tongji.edu.cn`
- **初始密码与用户名(学号/工号)相同**。 - 初始密码由程序随机生成, `users create` 执行后会自动导出凭据 CSV
示例文件见 `example/members.csv`。 示例文件见 `example/members.csv`。
@@ -209,15 +197,15 @@ uv sync --extra dev
### 运行测试 ### 运行测试
```bash ```bash
uv run pytest tests/ -v # 全部测试 uv run pytest tests/ -v --basetemp .pytest_tmp # 全部测试
uv run pytest tests/test_models.py # 只运行模型测试 uv run pytest tests/test_models.py --basetemp .pytest_tmp # 只运行模型测试
uv run pytest tests/ -k "password" # 按名称过滤 uv run pytest tests/ -k "password" --basetemp .pytest_tmp # 按名称过滤
``` ```
### 覆盖率报告 ### 覆盖率报告
```bash ```bash
uv run pytest tests/ --cov=tjhlp --cov-report=term-missing uv run pytest tests/ --cov=tjhlp --cov-report=term-missing --basetemp .pytest_tmp
``` ```
### 代码检查 ### 代码检查
@@ -271,7 +259,6 @@ scripts/
│ ├── test_models.py 数据模型测试 │ ├── test_models.py 数据模型测试
│ ├── test_config.py 配置校验测试 │ ├── test_config.py 配置校验测试
│ ├── test_utils.py 工具函数测试 │ ├── test_utils.py 工具函数测试
│ ├── test_pure_functions.py 纯函数测试
│ ├── test_client.py API 客户端测试 │ ├── test_client.py API 客户端测试
│ └── test_commands.py 命令集成测试 │ └── test_commands.py 命令集成测试
└── src/tjhlp/ └── src/tjhlp/
+95 -4
View File
@@ -3,7 +3,8 @@
import csv import csv
import secrets import secrets
import string import string
from datetime import UTC, datetime from dataclasses import dataclass
from datetime import datetime
from pathlib import Path from pathlib import Path
import typer import typer
@@ -18,6 +19,17 @@ app = typer.Typer(no_args_is_help=True)
console = Console() console = Console()
@dataclass
class CredentialRecord:
id: str
name: str
role: str
email: str
status: str
password: str
message: str
def _read_members_csv(filepath: Path) -> list[MemberRecord]: def _read_members_csv(filepath: Path) -> list[MemberRecord]:
"""读取 members CSV 文件""" """读取 members CSV 文件"""
records: list[MemberRecord] = [] records: list[MemberRecord] = []
@@ -28,13 +40,45 @@ def _read_members_csv(filepath: Path) -> list[MemberRecord]:
return records return records
def _generate_password(length: int = 12) -> str:
"""
生成随机密码 \\
仅包含字母和数字
"""
alphabet = string.ascii_letters + string.digits
return "".join(secrets.choice(alphabet) for _ in range(length))
def _write_credentials_csv(records: list[CredentialRecord]) -> Path:
output_path = Path(f"credentials_{datetime.now():%Y%m%d_%H%M%S}.csv")
with output_path.open("w", encoding="utf-8-sig", newline="") as f:
writer = csv.DictWriter(
f,
fieldnames=["id", "name", "role", "email", "status", "password", "message"],
)
writer.writeheader()
for record in records:
writer.writerow(
{
"id": record.id,
"name": record.name,
"role": record.role,
"email": record.email,
"status": record.status,
"password": record.password,
"message": record.message,
}
)
return output_path
@app.command("create") @app.command("create")
def create_users( def create_users(
file: Path = typer.Option(..., "--file", "-f", help="成员名单 CSV 文件路径"), file: Path = typer.Option(..., "--file", "-f", help="成员名单 CSV 文件路径"),
org: str = typer.Option("", "--org", help="自动添加到指定组织的对应团队"), org: str = typer.Option("", "--org", help="自动添加到指定组织的对应团队"),
dry_run: bool = typer.Option(False, "--dry-run", help="仅预览, 不实际创建"), dry_run: bool = typer.Option(False, "--dry-run", help="仅预览, 不实际创建"),
) -> None: ) -> None:
"""从 CSV 批量创建用户账号(初始密码与用户名相同)""" """从 CSV 批量创建用户账号(随机初始密码, 自动导出凭据 CSV)"""
if not file.exists(): if not file.exists():
console.print(f"[red]文件不存在: {file}[/red]") console.print(f"[red]文件不存在: {file}[/red]")
raise typer.Exit(code=1) raise typer.Exit(code=1)
@@ -59,6 +103,8 @@ def create_users(
return return
stats = {"created": 0, "skipped": 0, "failed": 0} stats = {"created": 0, "skipped": 0, "failed": 0}
# 用于记录创建结果
credential_records: list[CredentialRecord] = []
with GiteaClient(cfg) as client: with GiteaClient(cfg) as client:
# 获取团队 ID(如果指定了组织) # 获取团队 ID(如果指定了组织)
@@ -69,23 +115,36 @@ def create_users(
students_team = client.get_team_by_name(org, "students") students_team = client.get_team_by_name(org, "students")
for member in members: for member in members:
# 检查用户是否已存在 # 检查用户是否已存在,仅校验用户名是否存在
existing = client.get_user(member.username) existing = client.get_user(member.username)
if existing: if existing:
console.print(f" [yellow]跳过[/yellow] {member.username}({member.name})- 已存在") console.print(f" [yellow]跳过[/yellow] {member.username}({member.name})- 已存在")
stats["skipped"] += 1 stats["skipped"] += 1
credential_records.append(
CredentialRecord(
id=member.id,
name=member.name,
role=member.role,
email=member.email,
status="skipped",
password="",
message="user already exists",
)
)
continue continue
try: try:
password = _generate_password()
client.create_user( client.create_user(
username=member.username, username=member.username,
password=member.username, password=password,
email=member.email, email=member.email,
full_name=member.name, full_name=member.name,
must_change_password=True, must_change_password=True,
) )
console.print(f" [green]创建[/green] {member.username}({member.name})") console.print(f" [green]创建[/green] {member.username}({member.name})")
stats["created"] += 1 stats["created"] += 1
message = "created"
# 添加到团队 # 添加到团队
if org: if org:
@@ -95,14 +154,46 @@ def create_users(
client.add_team_member(team.id, member.username) client.add_team_member(team.id, member.username)
except GiteaClientError as e: except GiteaClientError as e:
console.print(f" [yellow]添加到团队失败: {e.message}[/yellow]") console.print(f" [yellow]添加到团队失败: {e.message}[/yellow]")
message = f"created; team assignment failed: {e.message}"
credential_records.append(
CredentialRecord(
id=member.id,
name=member.name,
role=member.role,
email=member.email,
status="created",
password=password,
message=message,
)
)
except GiteaClientError as e: except GiteaClientError as e:
console.print(f" [red]失败[/red] {member.username}({member.name}): {e.message}") console.print(f" [red]失败[/red] {member.username}({member.name}): {e.message}")
stats["failed"] += 1 stats["failed"] += 1
credential_records.append(
CredentialRecord(
id=member.id,
name=member.name,
role=member.role,
email=member.email,
status="failed",
password="",
message=e.message,
)
)
try:
output_path = _write_credentials_csv(credential_records)
except OSError as e:
console.print(f"[red]凭据导出失败: {e}[/red]")
console.print("[yellow]用户创建结果可能已部分生效, 请先检查 Gitea 中的实际状态, 不要直接重试整批导入。[/yellow]")
raise typer.Exit(code=1) from e
console.print( console.print(
f"\n完成: 创建 {stats['created']}, 跳过 {stats['skipped']}, 失败 {stats['failed']}" f"\n完成: 创建 {stats['created']}, 跳过 {stats['skipped']}, 失败 {stats['failed']}"
) )
console.print(f"凭据已导出: {output_path}")
@app.command("list") @app.command("list")
+94 -13
View File
@@ -2,7 +2,6 @@
from __future__ import annotations from __future__ import annotations
import csv
from pathlib import Path from pathlib import Path
from unittest.mock import MagicMock, patch from unittest.mock import MagicMock, patch
@@ -11,6 +10,7 @@ from pydantic import HttpUrl, SecretStr
from typer.testing import CliRunner from typer.testing import CliRunner
from tjhlp.cli import app from tjhlp.cli import app
from tjhlp.client import GiteaClient, GiteaClientError
from tjhlp.config import GiteaConfig, LabelDef from tjhlp.config import GiteaConfig, LabelDef
from tjhlp.models import GiteaRepo, GiteaTeam, GiteaUser from tjhlp.models import GiteaRepo, GiteaTeam, GiteaUser
@@ -104,9 +104,16 @@ class TestUsersCreateDryRun:
class TestUsersCreate: class TestUsersCreate:
@patch("tjhlp.commands.users.GiteaClient") @patch("tjhlp.commands.users.GiteaClient")
@patch("tjhlp.commands.users.get_gitea_config") @patch("tjhlp.commands.users.get_gitea_config")
def test_creates_users(self, mock_get_cfg, mock_client_cls, mock_config, tmp_path: Path): def test_creates_users(
self,
mock_get_cfg: MagicMock,
mock_client_cls: MagicMock,
mock_config: GiteaConfig,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch
):
mock_get_cfg.return_value = mock_config mock_get_cfg.return_value = mock_config
client = MagicMock() client = MagicMock(spec=GiteaClient)
client.__enter__ = MagicMock(return_value=client) client.__enter__ = MagicMock(return_value=client)
client.__exit__ = MagicMock(return_value=False) client.__exit__ = MagicMock(return_value=False)
client.get_user.return_value = None # user doesn't exist client.get_user.return_value = None # user doesn't exist
@@ -116,6 +123,7 @@ class TestUsersCreate:
csv_file = tmp_path / "members.csv" csv_file = tmp_path / "members.csv"
csv_file.write_text("id,name,role\n2659999,赵一伤,student\n", encoding="utf-8") csv_file.write_text("id,name,role\n2659999,赵一伤,student\n", encoding="utf-8")
monkeypatch.chdir(tmp_path)
result = runner.invoke( result = runner.invoke(
app, app,
@@ -125,22 +133,44 @@ class TestUsersCreate:
"--file", "--file",
str(csv_file), str(csv_file),
], ],
catch_exceptions=False,
) )
assert result.exit_code == 0 assert result.exit_code == 0
assert "创建" in result.output assert "创建" in result.output
client.create_user.assert_called_once_with( assert "凭据已导出:" in result.output
username="2659999", client.create_user.assert_called_once()
password="2659999", call_kwargs = client.create_user.call_args.kwargs
email="[email protected]", assert call_kwargs["username"] == "2659999"
full_name="赵一伤", assert call_kwargs["email"] == "[email protected]"
must_change_password=True, assert call_kwargs["full_name"] == "赵一伤"
) assert call_kwargs["must_change_password"] is True
assert call_kwargs["password"] != "2659999"
assert len(call_kwargs["password"]) >= 12
credential_files = list(tmp_path.glob("credentials_*.csv"))
assert len(credential_files) == 1
content = credential_files[0].read_text(encoding="utf-8-sig")
assert "created" in content
assert "2659999" in content
@patch("tjhlp.commands.users.GiteaClient") @patch("tjhlp.commands.users.GiteaClient")
@patch("tjhlp.commands.users.get_gitea_config") @patch("tjhlp.commands.users.get_gitea_config")
def test_skips_existing_user(self, mock_get_cfg, mock_client_cls, mock_config, tmp_path: Path): def test_skips_existing_user(
self,
mock_get_cfg: MagicMock,
mock_client_cls: MagicMock,
mock_config: GiteaConfig,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch
):
"""
测试内容:用户已存在时,是否正常导出凭据,且凭据中包含已存在的用户名和错误信息
预期:
- 用户已存在时,凭据导出文件中包含已存在的用户名和错误信息
"""
mock_get_cfg.return_value = mock_config mock_get_cfg.return_value = mock_config
client = MagicMock() client = MagicMock(spec=GiteaClient)
client.__enter__ = MagicMock(return_value=client) client.__enter__ = MagicMock(return_value=client)
client.__exit__ = MagicMock(return_value=False) client.__exit__ = MagicMock(return_value=False)
client.get_user.return_value = GiteaUser(id=1, login="2659999") # already exists client.get_user.return_value = GiteaUser(id=1, login="2659999") # already exists
@@ -148,11 +178,62 @@ class TestUsersCreate:
csv_file = tmp_path / "members.csv" csv_file = tmp_path / "members.csv"
csv_file.write_text("id,name,role\n2659999,赵一伤,student\n", encoding="utf-8") csv_file.write_text("id,name,role\n2659999,赵一伤,student\n", encoding="utf-8")
monkeypatch.chdir(tmp_path)
result = runner.invoke(app, ["users", "create", "--file", str(csv_file)]) result = runner.invoke(
app,
["users", "create", "--file", str(csv_file)],
catch_exceptions=False,
)
assert result.exit_code == 0 assert result.exit_code == 0
assert "跳过" in result.output assert "跳过" in result.output
client.create_user.assert_not_called() client.create_user.assert_not_called()
credential_files = list(tmp_path.glob("credentials_*.csv"))
assert len(credential_files) == 1
content = credential_files[0].read_text(encoding="utf-8-sig")
assert "skipped" in content
assert "user already exists" in content
@patch("tjhlp.commands.users.GiteaClient")
@patch("tjhlp.commands.users.get_gitea_config")
def test_exports_failed_user(
self,
mock_get_cfg: MagicMock,
mock_client_cls: MagicMock,
mock_config: GiteaConfig,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch
):
"""
测试内容:用户创建失败时,凭据是否正常导出
预期:
- 用户创建失败时,凭据导出文件中包含失败的用户名和错误信息
"""
mock_get_cfg.return_value = mock_config
client = MagicMock(spec=GiteaClient)
client.__enter__ = MagicMock(return_value=client)
client.__exit__ = MagicMock(return_value=False)
client.get_user.return_value = None
client.create_user.side_effect = GiteaClientError(400, "PasswordIsRequired")
mock_client_cls.return_value = client
csv_file = tmp_path / "members.csv"
csv_file.write_text("id,name,role\n2659999,赵一伤,student\n", encoding="utf-8")
monkeypatch.chdir(tmp_path)
result = runner.invoke(
app,
["users", "create", "--file", str(csv_file)],
catch_exceptions=False,
)
assert result.exit_code == 0
credential_files = list(tmp_path.glob("credentials_*.csv"))
assert len(credential_files) == 1
content = credential_files[0].read_text(encoding="utf-8-sig")
assert "failed" in content
assert "PasswordIsRequired" in content
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------