feat(deploy): 添加 Docker Compose 部署方案

新增 Docker Compose 部署方式,包含 Gitea 和 PostgreSQL 容器化配置
更新 README 文档说明两种部署方式
添加 .env 示例文件和 docker-compose.yml 配置文件

Signed-off-by: oierxjn <[email protected]>
This commit is contained in:
2026-04-22 21:46:55 +08:00
parent c338d39ed4
commit e94b5f1398
5 changed files with 243 additions and 5 deletions
+148
View File
@@ -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 [email protected]
```
将上面的 `admin` / `ChangeMe!2026` / `[email protected]` 替换为你在 `.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 默认不对宿主机暴露端口, 以减少额外暴露面