init commit

docs/superpowers/specs/2026-03-20-gitea-lan-deployment-design.md

@@ -0,0 +1,122 @@
+# Gitea 局域网部署设计
+
+## 概述
+
+使用 Docker Compose 在局域网中部署 Gitea Git 服务，支持 HTTP 和 SSH 访问，启用 Git LFS 支持。
+
+## 需求
+
+- 仅局域网使用
+- Docker Compose 容器化部署
+- 数据库：SQLite（简单可靠）
+- 访问方式：HTTP + SSH
+- 端口配置：通过 `.env` 文件灵活配置
+- 数据存储：宿主机目录挂载
+- 支持 Git LFS
+- 镜像版本：固定版本（避免 latest）
+
+## 技术选型
+
+| 组件 | 选择 | 说明 |
+|-----|------|-----|
+| Gitea 版本 | 1.25.4 | 当前最新稳定版 |
+| 数据库 | SQLite | 零配置，适合小规模使用 |
+| 容器镜像 | gitea/gitea:1.25.4 | 官方镜像，固定版本 |
+
+## 目录结构
+
+```
+gitea/
+├── docker-compose.yml    # 容器编排配置
+├── .env                  # 环境变量（端口等配置）
+├── .gitignore            # 忽略数据目录和敏感文件
+└── data/                 # Gitea 数据（挂载目录）
+    ├── git/              # Git 仓库数据
+    │   ├── repositories/ # 仓库存储
+    │   └── lfs/          # LFS 文件存储
+    ├── gitea/            # Gitea 配置和数据库
+    │   ├── gitea.db      # SQLite 数据库（用户数据）
+    │   └── conf/app.ini  # 配置文件
+    └── ssh/              # SSH 密钥
+```
+
+## 配置文件
+
+### .env - 环境变量
+
+```env
+# 镜像版本
+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
+```
+
+### docker-compose.yml
+
+- 镜像：`gitea/gitea:${GITEA_VERSION}`
+- 端口映射：
+  - `${HTTP_PORT}:3000` - Web 界面和 HTTP Git 操作
+  - `${SSH_PORT}:22` - SSH Git 操作
+- 数据卷挂载：`./data:/data`
+- 环境变量：从 `.env` 文件读取
+- 重启策略：`always`
+- 网络：bridge 模式
+
+### .gitignore
+
+忽略 `data/` 目录和 `.env` 文件（避免敏感信息提交）
+
+## 数据存储说明
+
+| 数据类型 | 容器内路径 | 宿主机路径 |
+|---------|-----------|-----------|
+| 用户账户、权限 | /data/gitea/gitea.db | ./data/gitea/gitea.db |
+| Git 仓库 | /data/git/repositories/ | ./data/git/repositories/ |
+| SSH 密钥 | /data/git/.ssh/ | ./data/git/.ssh/ |
+| LFS 文件 | /data/git/lfs/ | ./data/git/lfs/ |
+| 配置文件 | /data/gitea/conf/app.ini | ./data/gitea/conf/app.ini |
+
+## 使用方式
+
+### 启动服务
+
+```bash
+docker compose up -d
+```
+
+### 访问方式
+
+- Web 界面：`http://<服务器IP>:3000`
+- HTTP 克隆：`git clone http://<服务器IP>:3000/用户/仓库.git`
+- SSH 克隆：`git clone ssh://git@<服务器IP>:2222/用户/仓库.git`
+
+### 初始配置
+
+首次访问 Web 界面会进入安装向导，需要：
+1. 设置管理员账户
+2. 配置服务器域名等基本信息
+3. 数据库已使用 SQLite，无需额外配置
+
+### 备份
+
+备份 `./data/` 目录即可，特别是：
+- `./data/gitea/gitea.db` - 用户和配置数据
+- `./data/git/repositories/` - 仓库数据
+- `./data/git/lfs/` - LFS 文件
+
+## 文件清单
+
+需要创建的文件：
+1. `docker-compose.yml` - Docker Compose 配置
+2. `.env` - 环境变量配置
+3. `.gitignore` - Git 忽略规则
+4. `README.md` - 使用说明文档