175 lines
3.9 KiB
Markdown
175 lines
3.9 KiB
Markdown
# Gitea 局域网部署实现计划
|
||
|
||
> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 使用 Docker Compose 部署 Gitea Git 服务，支持 HTTP/SSH 访问、Git LFS 和 PostgreSQL 数据库
|
||
|
||
**Architecture:** Gitea + PostgreSQL 双容器部署，宿主机目录挂载持久化数据，通过 .env 文件配置端口和环境变量，Caddy 可选反向代理
|
||
|
||
**Tech Stack:** Docker Compose, Gitea 1.25.4, PostgreSQL 16 (alpine), Caddy 2 (可选)
|
||
|
||
---
|
||
|
||
## 文件结构
|
||
|
||
| 文件 | 职责 |
|
||
|-----|------|
|
||
| `docker-compose.yml` | 容器编排：Gitea + PostgreSQL + Caddy（可选） |
|
||
| `.env` | 可配置参数：版本、端口、时区、数据库、域名 |
|
||
| `.env.example` | 环境变量示例（无敏感信息） |
|
||
| `Caddyfile` | Caddy 反向代理配置 |
|
||
| `.gitignore` | 忽略数据目录和环境变量文件 |
|
||
| `README.md` | 使用说明：启动、访问、备份、迁移 |
|
||
|
||
---
|
||
|
||
## Chunk 1: 核心配置文件
|
||
|
||
### Task 1: 创建 .env 环境变量文件
|
||
|
||
**Files:**
|
||
- Create: `.env`
|
||
|
||
- [ ] **Step 1: 创建 .env 文件**
|
||
|
||
```env
|
||
# Gitea 版本
|
||
GITEA_VERSION=1.25.4
|
||
|
||
# 端口配置
|
||
HTTP_PORT=3000
|
||
SSH_PORT=2222
|
||
|
||
# 时区
|
||
TZ=Asia/Shanghai
|
||
|
||
# SSH 端口配置（告知 Gitea 对外 SSH 端口）
|
||
GITEA__server__SSH_PORT=${SSH_PORT}
|
||
|
||
# Git LFS 配置
|
||
GITEA__lfs__START_SERVER=true
|
||
GITEA__lfs__PATH=/data/git/lfs
|
||
|
||
# 禁用公开注册
|
||
GITEA__service__DISABLE_REGISTRATION=true
|
||
|
||
# PostgreSQL 配置
|
||
POSTGRES_VERSION=16-alpine
|
||
POSTGRES_DB=gitea
|
||
POSTGRES_USER=gitea
|
||
POSTGRES_PASSWORD=changeme
|
||
|
||
# 域名配置
|
||
DOMAIN=git.example.com
|
||
ROOT_URL=http://${DOMAIN}:${HTTP_PORT}/
|
||
```
|
||
|
||
- [ ] **Step 2: 验证文件创建成功**
|
||
|
||
Run: `cat .env`
|
||
Expected: 显示上述内容
|
||
|
||
---
|
||
|
||
### Task 2: 创建 docker-compose.yml
|
||
|
||
**Files:**
|
||
- Create: `docker-compose.yml`
|
||
|
||
- [ ] **Step 1: 创建 docker-compose.yml 文件**
|
||
|
||
关键配置：
|
||
- Gitea 服务：通过 `GITEA__database__*` 环境变量连接 PostgreSQL
|
||
- PostgreSQL 服务：`postgres:16-alpine`，健康检查 `pg_isready`
|
||
- Gitea `depends_on` PostgreSQL（健康检查通过后才启动）
|
||
- Caddy 服务：`profiles: [caddy]`，可选启用
|
||
|
||
- [ ] **Step 2: 验证 Docker Compose 配置语法**
|
||
|
||
Run: `docker compose config`
|
||
Expected: 无错误，显示解析后的配置
|
||
|
||
---
|
||
|
||
### Task 3: 创建 .gitignore
|
||
|
||
**Files:**
|
||
- Create: `.gitignore`
|
||
|
||
- [ ] **Step 1: 创建 .gitignore 文件**
|
||
|
||
```gitignore
|
||
# 数据目录
|
||
data/
|
||
|
||
# 环境变量（可能包含敏感信息）
|
||
.env
|
||
|
||
# Caddy 数据
|
||
caddy_data/
|
||
caddy_config/
|
||
|
||
# macOS
|
||
.DS_Store
|
||
```
|
||
|
||
---
|
||
|
||
### Task 4: 创建 .env.example
|
||
|
||
**Files:**
|
||
- Create: `.env.example`
|
||
|
||
- [ ] **Step 1: 创建 .env.example 文件**
|
||
|
||
与 `.env` 结构相同，但密码使用占位值 `changeme`。
|
||
|
||
---
|
||
|
||
## Chunk 2: 文档和验证
|
||
|
||
### Task 5: 创建 README.md 使用说明
|
||
|
||
**Files:**
|
||
- Create: `README.md`
|
||
|
||
- [ ] **Step 1: 创建 README.md 文件**
|
||
|
||
内容包含：
|
||
- 架构说明（HTTP 模式 / Caddy 模式）
|
||
- 快速开始（配置 → 启动 → 初始设置）
|
||
- 访问方式
|
||
- Git LFS 使用
|
||
- 数据备份（PostgreSQL pg_dump + 数据目录）
|
||
- SQLite 迁移到 PostgreSQL 步骤
|
||
- 常用命令
|
||
|
||
---
|
||
|
||
### Task 6: 最终验证
|
||
|
||
- [ ] **Step 1: 检查所有文件已创建**
|
||
|
||
Run: `ls -la`
|
||
Expected: 显示 `docker-compose.yml`, `.env`, `.env.example`, `.gitignore`, `README.md`
|
||
|
||
- [ ] **Step 2: 验证 Docker Compose 配置**
|
||
|
||
Run: `docker compose config`
|
||
Expected: 无错误输出，显示完整配置（包含 gitea、postgres、caddy 服务）
|
||
|
||
- [ ] **Step 3: （可选）启动服务测试**
|
||
|
||
Run: `docker compose up -d`
|
||
Expected: postgres 和 gitea 容器均启动成功
|
||
|
||
---
|
||
|
||
## 完成标准
|
||
|
||
- [ ] 所有配置文件已创建
|
||
- [ ] `docker compose config` 验证通过
|
||
- [ ] 服务可以正常启动（Gitea + PostgreSQL）
|
||
- [ ] 可以通过 Web 界面访问安装向导
|
||
- [ ] 数据库连接正常（安装向导中数据库类型显示为 PostgreSQL）
|