283 lines
5.0 KiB
Markdown
283 lines
5.0 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
|
||
|
||
**Architecture:** 单容器部署，SQLite 数据库，宿主机目录挂载持久化数据，通过 .env 文件配置端口和环境变量
|
||
|
||
**Tech Stack:** Docker Compose, Gitea 1.25.4, SQLite
|
||
|
||
---
|
||
|
||
## 文件结构
|
||
|
||
| 文件 | 职责 |
|
||
|-----|------|
|
||
| `docker-compose.yml` | 容器编排配置：镜像、端口、卷、环境变量 |
|
||
| `.env` | 可配置参数：版本、端口、时区、LFS 配置 |
|
||
| `.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
|
||
|
||
# Git LFS 配置
|
||
GITEA__lfs__START_SERVER=true
|
||
GITEA__lfs__PATH=/data/git/lfs
|
||
```
|
||
|
||
- [ ] **Step 2: 验证文件创建成功**
|
||
|
||
Run: `cat .env`
|
||
Expected: 显示上述内容
|
||
|
||
---
|
||
|
||
### Task 2: 创建 docker-compose.yml
|
||
|
||
**Files:**
|
||
- Create: `docker-compose.yml`
|
||
|
||
- [ ] **Step 1: 创建 docker-compose.yml 文件**
|
||
|
||
```yaml
|
||
services:
|
||
gitea:
|
||
image: gitea/gitea:${GITEA_VERSION}
|
||
container_name: gitea
|
||
environment:
|
||
- TZ=${TZ}
|
||
- GITEA__lfs__START_SERVER=${GITEA__lfs__START_SERVER}
|
||
- GITEA__lfs__PATH=${GITEA__lfs__PATH}
|
||
restart: always
|
||
volumes:
|
||
- ./data:/data
|
||
- /etc/timezone:/etc/timezone:ro
|
||
- /etc/localtime:/etc/localtime:ro
|
||
ports:
|
||
- "${HTTP_PORT}:3000"
|
||
- "${SSH_PORT}:22"
|
||
|
||
networks:
|
||
default:
|
||
driver: bridge
|
||
```
|
||
|
||
- [ ] **Step 2: 验证 Docker Compose 配置语法**
|
||
|
||
Run: `docker compose config`
|
||
Expected: 无错误，显示解析后的配置
|
||
|
||
---
|
||
|
||
### Task 3: 创建 .gitignore
|
||
|
||
**Files:**
|
||
- Create: `.gitignore`
|
||
|
||
- [ ] **Step 1: 创建 .gitignore 文件**
|
||
|
||
```gitignore
|
||
# 数据目录
|
||
data/
|
||
|
||
# 环境变量（可能包含敏感信息）
|
||
.env
|
||
|
||
# macOS
|
||
.DS_Store
|
||
```
|
||
|
||
- [ ] **Step 2: 验证文件创建成功**
|
||
|
||
Run: `cat .gitignore`
|
||
Expected: 显示上述内容
|
||
|
||
---
|
||
|
||
### Task 4: 创建 README.md 使用说明
|
||
|
||
**Files:**
|
||
- Create: `README.md`
|
||
|
||
- [ ] **Step 1: 创建 README.md 文件**
|
||
|
||
```markdown
|
||
# Gitea 局域网部署
|
||
|
||
使用 Docker Compose 部署的 Gitea Git 服务。
|
||
|
||
## 快速开始
|
||
|
||
### 1. 配置环境变量
|
||
|
||
复制并编辑 `.env` 文件：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
修改端口等配置：
|
||
|
||
```env
|
||
HTTP_PORT=3000 # Web 界面端口
|
||
SSH_PORT=2222 # SSH 端口
|
||
```
|
||
|
||
### 2. 启动服务
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
### 3. 初始配置
|
||
|
||
首次访问 `http://<服务器IP>:3000` 会进入安装向导：
|
||
|
||
1. 设置管理员账户
|
||
2. 配置服务器域名（可选）
|
||
3. 数据库已默认使用 SQLite
|
||
|
||
## 访问方式
|
||
|
||
| 方式 | 地址 |
|
||
|-----|------|
|
||
| Web 界面 | `http://<IP>:3000` |
|
||
| HTTP 克隆 | `git clone http://<IP>:3000/<用户>/<仓库>.git` |
|
||
| SSH 克隆 | `git clone ssh://git@<IP>:2222/<用户>/<仓库>.git` |
|
||
|
||
## Git LFS
|
||
|
||
已启用 Git LFS 支持，使用方法：
|
||
|
||
```bash
|
||
git lfs install
|
||
git lfs track "*.psd"
|
||
git add .gitattributes
|
||
git commit -m "Track PSD files with LFS"
|
||
git push
|
||
```
|
||
|
||
## 数据备份
|
||
|
||
备份 `data/` 目录：
|
||
|
||
```bash
|
||
# 备份
|
||
tar -czvf gitea-backup-$(date +%Y%m%d).tar.gz data/
|
||
|
||
# 恢复
|
||
tar -xzvf gitea-backup-20260320.tar.gz
|
||
```
|
||
|
||
重要文件：
|
||
- `data/gitea/gitea.db` - 用户和配置数据
|
||
- `data/git/repositories/` - 仓库数据
|
||
- `data/git/lfs/` - LFS 文件
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
# 启动
|
||
docker compose up -d
|
||
|
||
# 停止
|
||
docker compose down
|
||
|
||
# 查看日志
|
||
docker compose logs -f
|
||
|
||
# 重启
|
||
docker compose restart
|
||
|
||
# 更新版本
|
||
# 修改 .env 中的 GITEA_VERSION 后
|
||
docker compose up -d
|
||
```
|
||
```
|
||
|
||
- [ ] **Step 2: 验证文件创建成功**
|
||
|
||
Run: `cat README.md`
|
||
Expected: 显示上述内容
|
||
|
||
---
|
||
|
||
## Chunk 2: 创建示例配置和验证
|
||
|
||
### Task 5: 创建 .env.example 示例文件
|
||
|
||
**Files:**
|
||
- Create: `.env.example`
|
||
|
||
- [ ] **Step 1: 创建 .env.example 文件**
|
||
|
||
```env
|
||
# Gitea 版本
|
||
GITEA_VERSION=1.25.4
|
||
|
||
# 端口配置
|
||
HTTP_PORT=3000
|
||
SSH_PORT=2222
|
||
|
||
# 时区
|
||
TZ=Asia/Shanghai
|
||
|
||
# Git LFS 配置
|
||
GITEA__lfs__START_SERVER=true
|
||
GITEA__lfs__PATH=/data/git/lfs
|
||
```
|
||
|
||
- [ ] **Step 2: 验证文件创建成功**
|
||
|
||
Run: `cat .env.example`
|
||
Expected: 显示上述内容
|
||
|
||
---
|
||
|
||
### 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: 无错误输出，显示完整配置
|
||
|
||
- [ ] **Step 3: （可选）启动服务测试**
|
||
|
||
Run: `docker compose up -d`
|
||
Expected: 容器启动成功
|
||
|
||
---
|
||
|
||
## 完成标准
|
||
|
||
- [ ] 所有配置文件已创建
|
||
- [ ] `docker compose config` 验证通过
|
||
- [ ] 服务可以正常启动
|
||
- [ ] 可以通过 Web 界面访问安装向导
|