init commit

2026-03-20 15:58:32 +08:00
commit 58f31e698d
6 changed files with 538 additions and 0 deletions
--- a/docs/superpowers/plans/2026-03-20-gitea-lan-deployment.md
+++ b/docs/superpowers/plans/2026-03-20-gitea-lan-deployment.md
@@ -0,0 +1,282 @@
+# 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 界面访问安装向导