diff --git a/.gitignore b/.gitignore index 29e61d4..3ff98e9 100644 --- a/.gitignore +++ b/.gitignore @@ -33,3 +33,10 @@ Thumbs.db # OpenCode .opencode/ + +# Server inventory +ansible/inventory/hosts.yml +ansible/inventory/group_vars/all.yml + +# Docker Compose local config +deploy/compose/.env diff --git a/README.md b/README.md index 23e0cc2..ef5d820 100644 --- a/README.md +++ b/README.md @@ -18,26 +18,42 @@ ```text tjhlp-gitea/ ├── ansible/ Ansible 自动化部署(Gitea + PostgreSQL) +├── deploy/ 测试使用的部署方案(如 Docker Compose) ├── issue-templates/ Issue 模板(按仓库类型区分) └── 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。 ```bash cd ansible -# 编辑 inventory/hosts.yml 填入服务器地址 -# 编辑 inventory/group_vars/all.yml 修改域名、密码等 +cp inventory/hosts.yml.example inventory/hosts.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 会自动创建管理员账号并输出访问地址。 -### 2. 初始化平台 +### 3. 初始化平台 登录管理员账号, 在 **设置 -> 应用** 中创建 API Token, 然后: @@ -52,7 +68,7 @@ uv run tjhlp setup init --org tjhlp-2025f 这会创建课程组织、ta/students 团队、general 答疑仓库, 并推送 Issue Template 和预定义 Label。 -### 3. 导入用户 +### 4. 导入用户 准备 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 ``` -### 4. 创建作业仓库 +### 5. 创建作业仓库 ```bash 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 cd scripts uv sync --extra dev -uv run pytest tests/ -v # 运行全部测试 -uv run pytest tests/ --cov=tjhlp --cov-report=term-missing # 带覆盖率 +uv run pytest tests/ -v --basetemp .pytest_tmp # 运行全部测试 +uv run pytest tests/ --cov=tjhlp --cov-report=term-missing --basetemp .pytest_tmp # 带覆盖率 ``` 当前测试套件包含 99 个测试用例, 覆盖: @@ -123,7 +139,7 @@ yamllint issue-templates/ # YAML 语法 | Git 平台 | Gitea(二进制 + systemd) | | 数据库 | PostgreSQL 18 | | 服务器 | Rocky Linux 8.10 | -| 部署工具 | Ansible | +| 部署工具 | Ansible / Docker Compose | | 管理工具 | Python 3.14 + Typer + httpx + Pydantic + Dynaconf | | 包管理 | uv | | 测试框架 | pytest + respx + pytest-cov | diff --git a/ansible/inventory/group_vars/all.yml.example b/ansible/inventory/group_vars/all.yml.example new file mode 100644 index 0000000..ccfd136 --- /dev/null +++ b/ansible/inventory/group_vars/all.yml.example @@ -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: "shenjian@tongji.edu.cn" + +# ----------------------------------------------------------------------------- +# 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: "" diff --git a/ansible/inventory/hosts.yml.example b/ansible/inventory/hosts.yml.example new file mode 100644 index 0000000..1569faf --- /dev/null +++ b/ansible/inventory/hosts.yml.example @@ -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 diff --git a/deploy/compose/.env.example b/deploy/compose/.env.example new file mode 100644 index 0000000..7c9bdb9 --- /dev/null +++ b/deploy/compose/.env.example @@ -0,0 +1,28 @@ +# Copy this file to .env before running docker compose. + +# Image versions +GITEA_IMAGE=gitea/gitea:1.26.1 +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=admin@example.com diff --git a/deploy/compose/README.md b/deploy/compose/README.md new file mode 100644 index 0000000..c68e56a --- /dev/null +++ b/deploy/compose/README.md @@ -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 默认不对宿主机暴露端口, 以减少额外暴露面 diff --git a/deploy/compose/docker-compose.yml b/deploy/compose/docker-compose.yml new file mode 100644 index 0000000..56f446c --- /dev/null +++ b/deploy/compose/docker-compose.yml @@ -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: diff --git a/deploy/compose/init-admin.sh b/deploy/compose/init-admin.sh new file mode 100644 index 0000000..88c077a --- /dev/null +++ b/deploy/compose/init-admin.sh @@ -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." diff --git a/scripts/.gitignore b/scripts/.gitignore index 054077c..a66fe74 100644 --- a/scripts/.gitignore +++ b/scripts/.gitignore @@ -9,6 +9,7 @@ build/ *.egg # Pytest +.pytest_tmp/ .coverage # Secrets & credentials diff --git a/scripts/README.md b/scripts/README.md index 4fd34c0..c81eaf8 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -1,6 +1,6 @@ # Python CLI 管理工具 -`tjhlp` 是课程答疑平台的命令行管理工具, 通过 Gitea REST API 批量管理用户、组织、仓库、Webhook、Label, 并提供 Issue 统计和邮件通知功能。 +`tjhlp` 是课程答疑平台的命令行管理工具, 通过 Gitea REST API 批量管理用户、组织、仓库、Webhook、Label, 并提供 Issue 统计功能。 ## 前置要求 @@ -28,7 +28,7 @@ uv sync cp .secrets.toml.example .secrets.toml ``` -编辑 `.secrets.toml`, 填入实际值: +编辑 `.secrets.toml`, 填入实际值: ```toml [default.gitea] @@ -41,7 +41,7 @@ API Token 获取方式: 登录 Gitea -> 设置 -> 应用 -> 生成令牌(勾选 ### 环境变量覆盖 -所有配置项均可通过 `TJHLP_` 前缀的环境变量覆盖: +所有配置项均可通过 `TJHLP_` 前缀的环境变量覆盖: ```bash export TJHLP_GITEA_URL=http://192.168.1.100:3000 @@ -56,7 +56,7 @@ tjhlp │ ├── init 一键初始化: 创建组织/团队/仓库/Labels/Webhook │ └── status 检查 Gitea 连接状态 ├── users -│ ├── create 从 CSV 批量创建账号(随机密码) +│ ├── create 从 CSV 批量创建账号(随机初始密码, 自动导出凭据 CSV) │ ├── list 列出所有用户 │ └── delete 批量删除用户 ├── orgs @@ -77,12 +77,9 @@ tjhlp ├── labels │ ├── sync 同步预定义 Label 到仓库 │ └── list 列出仓库 Label -├── stats -│ ├── summary Issue 统计摘要 -│ └── export 导出 Issue 数据到 CSV -└── labels - ├── sync 同步预定义 Label 到仓库 - └── list 列出仓库 Label +└── stats + ├── summary Issue 统计摘要 + └── export 导出 Issue 数据到 CSV ``` ## 典型工作流 @@ -103,29 +100,14 @@ uv run tjhlp setup init \ uv run tjhlp users create --file members.csv --org tjhlp-2025f ``` +执行完成后会自动生成 `credentials_YYYYMMDD_HHMMSS.csv`, 包含账号、随机初始密码和处理状态。 -## 典型工作流 +`cmd` 可直接复制的写法: -### 学期初始化 - -```bash -# 1. 检查连接 +```cmd 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 setup init --org tjhlp-2025f --webhook-url http://notify-server:8080/webhook --webhook-secret mysecret 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 ``` +`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 团队。 ### 日常管理 @@ -174,16 +162,16 @@ id,name,role ``` - `id` - 学号或工号, 同时作为 Gitea 用户名 -- `name` - 姓名, 作为 Gitea 的 full_name +- `name` - 姓名, 作为 Gitea 的 `full_name` - `role` - `student` 或 `ta`, 决定分配到哪个团队 - 邮箱自动生成为 `{id}@tongji.edu.cn` -- **初始密码与用户名(学号/工号)相同**。 +- 初始密码由程序随机生成, `users create` 执行后会自动导出凭据 CSV 示例文件见 `example/members.csv`。 ## 预定义 Label -通过 `settings.toml` 配置, `setup init` 和 `labels sync` 时自动创建: +通过 `settings.toml` 配置, `setup init` 和 `labels sync` 时自动创建: | Label | 颜色 | 用途 | |-------|------|------| @@ -209,15 +197,15 @@ uv sync --extra dev ### 运行测试 ```bash -uv run pytest tests/ -v # 全部测试 -uv run pytest tests/test_models.py # 只运行模型测试 -uv run pytest tests/ -k "password" # 按名称过滤 +uv run pytest tests/ -v --basetemp .pytest_tmp # 全部测试 +uv run pytest tests/test_models.py --basetemp .pytest_tmp # 只运行模型测试 +uv run pytest tests/ -k "password" --basetemp .pytest_tmp # 按名称过滤 ``` ### 覆盖率报告 ```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_config.py 配置校验测试 │ ├── test_utils.py 工具函数测试 -│ ├── test_pure_functions.py 纯函数测试 │ ├── test_client.py API 客户端测试 │ └── test_commands.py 命令集成测试 └── src/tjhlp/ diff --git a/scripts/src/tjhlp/commands/users.py b/scripts/src/tjhlp/commands/users.py index 3e236b2..d2a81e9 100644 --- a/scripts/src/tjhlp/commands/users.py +++ b/scripts/src/tjhlp/commands/users.py @@ -3,7 +3,8 @@ import csv import secrets import string -from datetime import UTC, datetime +from dataclasses import dataclass +from datetime import datetime from pathlib import Path import typer @@ -18,6 +19,17 @@ app = typer.Typer(no_args_is_help=True) 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]: """读取 members CSV 文件""" records: list[MemberRecord] = [] @@ -28,13 +40,45 @@ def _read_members_csv(filepath: Path) -> list[MemberRecord]: 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") def create_users( file: Path = typer.Option(..., "--file", "-f", help="成员名单 CSV 文件路径"), org: str = typer.Option("", "--org", help="自动添加到指定组织的对应团队"), dry_run: bool = typer.Option(False, "--dry-run", help="仅预览, 不实际创建"), ) -> None: - """从 CSV 批量创建用户账号(初始密码与用户名相同)""" + """从 CSV 批量创建用户账号(随机初始密码, 自动导出凭据 CSV)""" if not file.exists(): console.print(f"[red]文件不存在: {file}[/red]") raise typer.Exit(code=1) @@ -59,6 +103,8 @@ def create_users( return stats = {"created": 0, "skipped": 0, "failed": 0} + # 用于记录创建结果 + credential_records: list[CredentialRecord] = [] with GiteaClient(cfg) as client: # 获取团队 ID(如果指定了组织) @@ -69,23 +115,36 @@ def create_users( students_team = client.get_team_by_name(org, "students") for member in members: - # 检查用户是否已存在 + # 检查用户是否已存在,仅校验用户名是否存在 existing = client.get_user(member.username) if existing: console.print(f" [yellow]跳过[/yellow] {member.username}({member.name})- 已存在") 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 try: + password = _generate_password() client.create_user( username=member.username, - password=member.username, + password=password, email=member.email, full_name=member.name, must_change_password=True, ) console.print(f" [green]创建[/green] {member.username}({member.name})") stats["created"] += 1 + message = "created" # 添加到团队 if org: @@ -95,14 +154,46 @@ def create_users( client.add_team_member(team.id, member.username) except GiteaClientError as e: 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: console.print(f" [red]失败[/red] {member.username}({member.name}): {e.message}") 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( f"\n完成: 创建 {stats['created']}, 跳过 {stats['skipped']}, 失败 {stats['failed']}" ) + console.print(f"凭据已导出: {output_path}") @app.command("list") diff --git a/scripts/tests/test_commands.py b/scripts/tests/test_commands.py index 523e2c1..b0a9899 100644 --- a/scripts/tests/test_commands.py +++ b/scripts/tests/test_commands.py @@ -2,7 +2,6 @@ from __future__ import annotations -import csv from pathlib import Path from unittest.mock import MagicMock, patch @@ -11,6 +10,7 @@ from pydantic import HttpUrl, SecretStr from typer.testing import CliRunner from tjhlp.cli import app +from tjhlp.client import GiteaClient, GiteaClientError from tjhlp.config import GiteaConfig, LabelDef from tjhlp.models import GiteaRepo, GiteaTeam, GiteaUser @@ -104,9 +104,16 @@ class TestUsersCreateDryRun: class TestUsersCreate: @patch("tjhlp.commands.users.GiteaClient") @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 - client = MagicMock() + client = MagicMock(spec=GiteaClient) client.__enter__ = MagicMock(return_value=client) client.__exit__ = MagicMock(return_value=False) client.get_user.return_value = None # user doesn't exist @@ -116,6 +123,7 @@ class TestUsersCreate: 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, @@ -125,22 +133,44 @@ class TestUsersCreate: "--file", str(csv_file), ], + catch_exceptions=False, ) assert result.exit_code == 0 assert "创建" in result.output - client.create_user.assert_called_once_with( - username="2659999", - password="2659999", - email="2659999@tongji.edu.cn", - full_name="赵一伤", - must_change_password=True, - ) + assert "凭据已导出:" in result.output + client.create_user.assert_called_once() + call_kwargs = client.create_user.call_args.kwargs + assert call_kwargs["username"] == "2659999" + assert call_kwargs["email"] == "2659999@tongji.edu.cn" + 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.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 - client = MagicMock() + client = MagicMock(spec=GiteaClient) client.__enter__ = MagicMock(return_value=client) client.__exit__ = MagicMock(return_value=False) 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.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 "跳过" in result.output 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 # ---------------------------------------------------------------------------