From e94b5f13980e6f0a01a7e051b692585a2c67a25d9528e725d838f30b4eccd860 Mon Sep 17 00:00:00 2001 From: oierxjn <1934672944@qq.com> Date: Wed, 22 Apr 2026 21:46:55 +0800 Subject: [PATCH] =?UTF-8?q?feat(deploy):=20=E6=B7=BB=E5=8A=A0=20Docker=20C?= =?UTF-8?q?ompose=20=E9=83=A8=E7=BD=B2=E6=96=B9=E6=A1=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 Docker Compose 部署方式,包含 Gitea 和 PostgreSQL 容器化配置 更新 README 文档说明两种部署方式 添加 .env 示例文件和 docker-compose.yml 配置文件 Signed-off-by: oierxjn <1934672944@qq.com> --- .gitignore | 3 + README.md | 20 +++- deploy/compose/.env.example | 28 ++++++ deploy/compose/README.md | 148 ++++++++++++++++++++++++++++++ deploy/compose/docker-compose.yml | 49 ++++++++++ 5 files changed, 243 insertions(+), 5 deletions(-) create mode 100644 deploy/compose/.env.example create mode 100644 deploy/compose/README.md create mode 100644 deploy/compose/docker-compose.yml 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..9bfc57c 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..d6207fa --- /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 to create manually after startup +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..39588c2 --- /dev/null +++ b/deploy/compose/README.md @@ -0,0 +1,148 @@ +# Docker Compose 部署 + + +- 目标: 单机容器部署 `Gitea + PostgreSQL` +- 不包含: Nginx、TLS 证书、外部对象存储、多节点编排 +- 上层使用方式不变: 服务启动后仍然使用 `scripts/` 里的 `tjhlp` CLI 初始化课程组织、仓库、标签和 Webhook + +## 文件说明 + +- `docker-compose.yml`: 启动 Gitea 与 PostgreSQL +- `.env.example`: 本地变量模板, 复制为 `.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 docker compose exec gitea \ + gitea admin user create \ + --admin \ + --username admin \ + --password 'ChangeMe!2026' \ + --email admin@example.com +``` + +将上面的 `admin` / `ChangeMe!2026` / `admin@example.com` 替换为你在 `.env` 中准备好的值。 + +如果你在 Windows PowerShell 中执行, 使用: + +```powershell +sudo docker compose exec gitea ` + gitea admin user create ` + --admin ` + --username admin ` + --password 'ChangeMe!2026' ` + --email admin@example.com +``` + +创建完成后, 访问 `GITEA_ROOT_URL`, 用管理员账号登录。 + +## 课程平台初始化 + +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..7b8c232 --- /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/data + + 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: