diff --git a/.gitignore b/.gitignore index 120ced4..3ff98e9 100644 --- a/.gitignore +++ b/.gitignore @@ -37,3 +37,6 @@ Thumbs.db # 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 1bf0d8d..6723103 100644 --- a/README.md +++ b/README.md @@ -18,13 +18,23 @@ ```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。 @@ -43,7 +53,7 @@ ansible-playbook playbook.yml 部署完成后, Ansible 会自动创建管理员账号并输出访问地址。 -### 2. 初始化平台 +### 3. 初始化平台 登录管理员账号, 在 **设置 -> 应用** 中创建 API Token, 然后: @@ -58,7 +68,7 @@ uv run tjhlp setup init --org tjhlp-2025f 这会创建课程组织、ta/students 团队、general 答疑仓库, 并推送 Issue Template 和预定义 Label。 -### 3. 导入用户 +### 4. 导入用户 准备 CSV 文件(格式见 `scripts/example/members.csv`): @@ -73,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 @@ -129,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/deploy/compose/.env.example b/deploy/compose/.env.example new file mode 100644 index 0000000..792a4e6 --- /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.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=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."