llm_wiki/wiki/Gitea-部署指南.md

---
categories:
  - '[[LLM Wiki]]'
tags:
  - wiki
  - concept
  - gitea
  - deployment
  - frp
  - nas
created: 2026-04-07
source: '[[Gitea个人Git服务部署指南]]'
type: concept
aliases:
  - 自建Git服务
  - NAS代码仓库
  - FRP内网穿透
relations:
  - type: extends
    target: '[[Gitea-故障排查]]'
    confidence: 2
  - type: extends
    target: '[[FRP]]'
    confidence: 2
---

[raw:Gitea个人Git服务部署指南:2]# Gitea 部署指南

> **一句话描述**：在群晖 NAS 上部署 Gitea + FRP 实现个人 Git 服务的公网访问

## 背景

在群晖 NAS 上部署 Gitea 代码仓库服务，通过 FRP 内网穿透暴露到公网，实现个人代码仓库的远程访问。相比 QuickConnect，FRP 提供更稳定的连接和更快的访问速度。

### 两种部署方案

| 方案 | 架构 | 优势 | 适用场景 |
|
------|
------|------|----------|
| **NAS 方案** | NAS + Gitea + FRP | 配置简单，无需额外 VPS | 已有 NAS，设备较少 |
| **VPS 方案** | VPS + Nginx + FRP + NAS + Gitea | HTTPS 自动化，可扩展多服务 | 需要独立域名，希望更稳定 |

**本指南重点**：NAS 方案（群晖 + Gitea + FRP）
**VPS 方案参考**：本指南后文的"VPS 方案"章节

---

## 环境概览

### 硬件环境

| 配置项 | 值 |
|--------|-----|
| NAS 型号 | Synology DS418play |
| CPU 架构 | Intel Celeron J3355 (x86_64) |
| 系统版本 | DSM 7.3.2-86009 Update 3 |
| 域名 | haiguang.xyz |

### 软件版本

| 软件 | 版本 | 说明 |
|------|------|------|
| Gitea | 1.25.5-28 | SynoCommunity 套件 |
| FRP | v0.68.0 | 最新版（2026-03-20 发布） |
| MariaDB | 10 | 群晖套件（监听 3307 端口） |

### 网络环境

| 服务 | 地址 |
|------|------|
| FRP 服务器 | 82.156.57.104:7000 |
| QuickConnect | hehaiguang.cn4.quickconnect.cn |
| 公网访问 | git.haiguang.xyz |

---

## 部署架构

### NAS 方案（本指南重点）

```mermaid
graph LR
    A[开发者] --> B[git.haiguang.xyz]
    B --> C[FRP服务器<br/>82.156.57.104]
    C --> D[FRP客户端<br/>群晖NAS]
    D --> E[Gitea服务<br/>端口8418]

    F[SSH访问] --> G[82.156.57.104:10022]
    G --> D
    D --> H[SSH服务<br/>端口10022]
```

**流量路径**：

1. **HTTP 访问**：`git.haiguang.xyz` → DNS 解析到 `82.156.57.104` → FRP 服务器端口 13000 → FRP 客户端 → Gitea 本地端口 8418
2. **SSH 访问**：`82.156.57.104:10022` → FRP 服务器 → FRP 客户端 → Gitea SSH 端口 10022

### VPS 方案（参考）

```mermaid
graph LR
    A[用户浏览器] -->|HTTPS| B[腾讯云VPS<br/>82.156.57.104]
    A -->|git clone/push| B
    B -->|Nginx反代| C[frps:13000]
    C -->|FRP隧道<br/>TLS加密| D[frpc]
    D -->|TCP| E[NAS Gitea:8418]
```

**VPS 端口映射**：

| 位置 | 端口 | 服务 |
|------|------|------|
| VPS | 7000 | frps 通信 |
| VPS | 13000 | frps 代理（Gitea Web） |
| VPS | 10022 | frps 代理（Gitea SSH） |
| VPS | 443 | Nginx HTTPS |
| VPS | 80 | Nginx HTTP → HTTPS |

---

## 方案选型

> [!tip] 选型结论
> 经过对比 Gitea vs Gogs、SQLite vs MySQL/PostgreSQL、FRP vs Tailscale，最终选择：**Gitea + SQLite + FRP**。

### Gitea vs Gogs vs GitLab

| 维度 | Gitea ✅ | Gogs | GitLab ❌ |
|------|---------|------|---------|
| 最低内存 | ~200MB | ~100MB | ≥4GB |
| 功能完整度 | PR/Actions/包管理/Wiki | 基础 | 全功能 |
| CI/CD | 内置 Actions | 需外接 | 内置 |
| 社区活跃度 | 非常活跃 | 维护模式 | 活跃 |

### 数据库选型

| 维度 | SQLite ✅ | MySQL | PostgreSQL | CouchDB（已有） |
|------|---------|-------|-----------|---------------|
| 额外内存 | 0 | ~200MB | ~200MB | ~43MB |
| 额外部署 | 无 | 需安装 | 需安装 | 已有 |
| Gitea 支持 | ✅ | ✅ | ✅ | ❌ |

### 内网穿透选型

| 维度 | FRP ✅ | Tailscale | Cloudflare Tunnel |
|------|--------|-----------|-------------------|
| 每台设备装客户端 | 不需要 | 需要 | 不需要 |
| 传输方式 | 中继 | P2P 优先 | 中继 |
| 部署复杂度 | 低 | 中 | 中 |
| 适用场景 | 少设备通用访问 | 多设备频繁访问 | HTTP-only |

> [!warning] Tailscale 不选的原因
> - 家宽 NAT 穿透不稳定，手机 4G 大概率走 DERP 中继（速度与 FRP 相当）
> - 每台设备都要装客户端，临时借用电脑不方便
> - VPS 带宽才是瓶颈（~2.8Mbps），P2P 优势有限

---

## VPS 方案部署（参考）

### VPS 环境信息

| 项目 | 值 |
|------|-----|
| 系统 | Ubuntu 24.04.4 LTS |
| CPU | 2 核 AMD EPYC 7K62 |
| 内存 | 2GB（可用约 640MB） |
| 磁盘 | 40GB（可用 14GB） |
| 公网 IP | 82.156.57.104 |
| 已有服务 | Nginx、OpenClaw Gateway、CouchDB |

### 第一步：FRP 服务端部署（VPS）

**1. 下载安装**

```bash
# 下载 FRP v0.68.0
wget https://github.com/fatedier/frp/releases/download/v0.68.0/frp_0.68.0_linux_amd64.tar.gz
tar -xzf frp_0.68.0_linux_amd64.tar.gz -C /opt/
mv /opt/frp_0.68.0_linux_amd64 /opt/frp
ln -s /opt/frp/frps /usr/local/bin/frps
```

**2. 配置 frps.toml**

```toml
# FRP 服务端配置
bindPort = 7000              # 客户端连接端口

[auth]
token = "你的强密码"           # 认证令牌（两端必须一致）

[transport]
tls.force = true             # 强制 TLS 加密

[webServer]
addr = "127.0.0.1"           # Dashboard 仅本地访问
port = 7500
user = "admin"
password = "你的密码"
```

**3. systemd 服务**

```ini
# /etc/systemd/system/frps.service
[Unit]
Description=FRP Server Service
After=network.target

[Service]
Type=simple
User=nobody
Restart=on-failure
RestartSec=5s
ExecStart=/usr/local/bin/frps -c /opt/frp/frps.toml

[Install]
WantedBy=multi-user.target
```

**4. 启动**

```bash
systemctl daemon-reload
systemctl enable --now frps
```

**5. 腾讯云安全组放行**

| 端口 | 协议 | 来源 | 用途 |
|------|------|------|------|
| 7000 | TCP | 0.0.0.0/0 | FRP 通信 |
| 13000 | TCP | 0.0.0.0/0 | Gitea Web |
| 10022 | TCP | 0.0.0.0/0 | Gitea SSH（可选） |

### 第二步：Nginx 反向代理 + HTTPS

**1. HTTP 反代配置**

```nginx
# /etc/nginx/sites-available/gitea
server {
    listen 80;
    listen [::]:80;
    server_name git.haiguang.xyz;

    access_log /var/log/nginx/gitea-access.log;
    error_log /var/log/nginx/gitea-error.log;

    location / {
        proxy_pass http://127.0.0.1:13000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        client_max_body_size 100m;
    }
}
```

**2. Let's Encrypt 证书**

```bash
# 安装 certbot
apt install certbot python3-certbot-nginx

# 签发证书并自动配置 HTTPS
certbot --nginx -d git.haiguang.xyz
```

certbot 会自动修改 Nginx 配置，添加 HTTPS 监听和证书路径。

### 第三步：FRP 客户端配置（NAS）

VPS 方案下的 FRP 客户端配置与 NAS 方案相同，见"部署步骤"章节。

### VPS 方案文件路径

| 文件 | 路径 |
|------|------|
| frps 二进制 | /usr/local/bin/frps |
| frps 配置 | /opt/frp/frps.toml |
| frps 服务 | /etc/systemd/system/frps.service |
| Nginx Gitea 配置 | /etc/nginx/sites-available/gitea |
| HTTPS 证书 | /etc/letsencrypt/live/git.haiguang.xyz/ |
| HTTPS 密钥 | /etc/letsencrypt/live/git.haiguang.xyz/privkey.pem |

---

## NAS 方案部署步骤

## 环境概览

### 硬件环境

| 配置项 | 值 |
|--------|-----|
| NAS 型号 | Synology DS418play |
| CPU 架构 | Intel Celeron J3355 (x86_64) |
| 系统版本 | DSM 7.3.2-86009 Update 3 |
| 域名 | haiguang.xyz |

### 软件版本

| 软件      | 版本        | 说明                 |
| ------- | --------- | ------------------ |
| Gitea   | 1.25.5-28 | SynoCommunity 套件   |
| FRP     | v0.68.0   | 最新版（2026-03-20 发布） |
| MariaDB | 10        | 群晖套件（监听 3307 端口）   |

### 网络环境

| 服务 | 地址 |
|------|------|
| FRP 服务器 | 82.156.57.104:7000 |
| QuickConnect | hehaiguang.cn4.quickconnect.cn |
| 公网访问 | git.haiguang.xyz |

## 部署架构

```mermaid
graph LR
    A[开发者] --> B[git.haiguang.xyz]
    B --> C[FRP服务器<br/>82.156.57.104]
    C --> D[FRP客户端<br/>群晖NAS]
    D --> E[Gitea服务<br/>端口8418]

    F[SSH访问] --> G[82.156.57.104:10022]
    G --> D
    D --> H[SSH服务<br/>端口10022]
```

### 流量路径

1. **HTTP 访问**：`git.haiguang.xyz` → DNS 解析到 `82.156.57.104` → FRP 服务器端口 13000 → FRP 客户端 → Gitea 本地端口 8418
2. **SSH 访问**：`82.156.57.104:10022` → FRP 服务器 → FRP 客户端 → Gitea SSH 端口 10022

## 部署步骤

### 第一阶段：Gitea 服务安装

#### 1. 安装 Gitea 套件

从 SynoCommunity 安装 Gitea 套件：

- 套件中心 → 设置 → 套件来源 → 新增
- 名称: SynoCommunity
- 位置: `https://packages.synocommunity.com/`
- 搜索并安装 Gitea

#### 2. 初始化配置

访问 `http://192.168.123.21:8418` 进行初始化：

**数据库配置**：

```
数据库类型: SQLite3
数据库文件: /var/packages/gitea/var/data/gitea.db
```

> [!tip] 数据库选择建议
> - **SQLite3**: 零配置，适合个人使用（≤50 仓库）
> - **MariaDB**: 性能更好，适合团队协作
> - 注意：群晖 MariaDB 监听 **3307** 端口（非标准 3306）

**应用配置**：

```
仓库存储路径: /volume3/gitea-share/gitea-repositories
管理员账号: giteahhg
密码: [你的密码]
```

### 第二阶段：FRP 客户端部署

#### 1. 配置文件 (frpc.toml)

```toml
serverAddr = "82.156.57.104"
serverPort = 7000
auth.method = "token"
auth.token = "deb19f52ac7fa6423efcd1a3fbf9c2b7"
transport.tls.enable = true
log.to = "/var/log/frpc.log"
log.level = "info"
log.maxDays = 7

[[proxies]]
name = "gitea-web"
type = "tcp"
localIP = "127.0.0.1"
localPort = 8418
remotePort = 13000

[[proxies]]
name = "gitea-ssh"
type = "tcp"
localIP = "127.0.0.1"
localPort = 10022
remotePort = 10022
```

> [!warning] 关键配置说明
> - **type**: 必须使用 `tcp`，HTTP 类型需要服务器配置 vhost
> - **localPort**: Gitea 实际运行端口（非标准 3000）
> - **remotePort**: 服务器开放端口，避免使用 3000（易冲突）

#### 2. 部署到群晖

将以下文件上传到群晖 `/volume1/docker/frpc/`：

- frpc.toml（配置文件）
- frp_0.68.0_linux_amd64.tar.gz（从 GitHub 下载）
- install-local.sh（安装脚本）
- start-frpc.sh（启动脚本）
- stop-all-frpc.sh（停止脚本）
- status-frpc.sh（状态检查）

#### 3. 执行部署

通过群晖任务计划执行：

```bash
# 安装 FRP
bash /volume1/docker/frpc/install-local.sh

# 启动客户端
bash /volume1/docker/frpc/start-frpc.sh

# 检查状态
bash /volume1/docker/frpc/status-frpc.sh
```

> [!danger] 常见错误：脚本执行失败
> **问题**: 任务计划执行后"标准输出/错误无内容"
> **原因**: Windows 换行符（CRLF）导致 bash 无法解析
> **解决**: 使用 `bash` 显式调用脚本，而非直接执行

### 第三阶段：配置更新

#### 1. 更新 ROOT_URL 和安全配置

编辑 `/var/packages/gitea/var/conf.ini`：

```ini
[server]
ROOT_URL = https://git.haiguang.xyz/
DOMAIN = git.haiguang.xyz
SSH_DOMAIN = git.haiguang.xyz

[service]
DISABLE_REGISTRATION = true          # 禁用公开注册
ENABLE_OPENID_SIGNUP = false
```

重启服务：

```bash
synopkg restart gitea
```

#### 2. 配置 DNS 解析

在域名服务商添加 A 记录：

| 类型 | 主机记录 | 记录值 | TTL |
|------|----------|--------|-----|
| A | git | 82.156.57.104 | 600 |

## 关键参数清单

### Gitea 配置

> [!important] 重要：配置文件路径
> 群晖 Gitea 套件的配置文件路径为：**`/var/packages/gitea/var/conf.ini`**
> 
> 很多文档错误地认为是 `/var/packages/gitea/var/app.ini`，这是不正确的。

| 参数 | 值 | 文件位置 |
|------|-----|----------|
| 本地端口 | 8418 | `/var/packages/gitea/var/conf.ini` |
| SSH 端口 | 10022 | 同上 |
| 数据库 | SQLite3 | `/var/packages/gitea/var/data/gitea.db` |
| 仓库目录 | `/volume3/gitea-share/gitea-repositories` | 初始化时设置 |
| ROOT_URL | `https://git.haiguang.xyz/` | 需手动更新 |
| 运行用户 | sc-gitea | 套件自动创建 |

### FRP 配置

| 参数 | 值 | 说明 |
|------|-----|------|
| 服务器地址 | 82.156.57.104 | FRP 服务器 IP |
| 服务器端口 | 7000 | FRP 服务端口 |
| 认证 Token | deb19f52ac7fa6423efcd1a3fbf9c2b7 | 服务端配置 |
| TLS 加密 | 启用 | 安全传输 |
| Web 代理 | 本地 8418 → 远程 13000 | TCP 模式 |
| SSH 代理 | 本地 10022 → 远程 10022 | TCP 模式 |

## 经验教训

### 问题 1：脚本执行失败

**现象**：群晖任务计划执行脚本后无输出，服务未启动

**根本原因**：
- Windows 环境创建的脚本使用 CRLF 换行符
- 群晖 bash 无法解析 CRLF 格式
- 直接执行 `./script.sh` 会静默失败

**解决方案**：

```bash
# 错误方式
./install-local.sh

# 正确方式
bash install-local.sh
```

**预防措施**：
- 使用 VSCode 统一换行符为 LF
- 或在脚本开头添加 `#!/bin/bash` 并用 bash 显式调用

### 问题 2：HTTP 代理不支持

**现象**：FRP 日志显示 `type [http] not supported`

**根本原因**：
- FRP 服务器未配置 `vhostHTTPPort`
- HTTP 类型代理需要服务端支持虚拟主机

**解决方案**：

改用 TCP 模式：

```toml
[[proxies]]
name = "gitea-web"
type = "tcp"  # 原为 "http"
localPort = 8418
remotePort = 13000
```

**对比**：

| 模式 | 优势 | 劣势 | 适用场景 |
|------|------|------|----------|
| HTTP | 支持域名路由，可共享 80 端口 | 需服务端配置 | 多服务共享域名 |
| TCP | 无需额外配置，通用性强 | 每服务需独立端口 | 单服务部署 |

### 问题 3：端口冲突

**现象**：Gitea 服务无法启动或 FRP 代理失败

**排查过程**：

1. 检查 Gitea 实际端口：`netstat -tuln | grep gitea` → 发现 8418
2. 检查 FRP 端口占用：`netstat -tuln | grep 3000` → VPS 已占用
3. 检查多实例：`ps aux | grep frpc` → 发现两个进程

**解决方案**：

```bash
# 清理所有 frpc 进程
kill -9 $(pgrep frpc)

# 修改 remotePort 为非标准端口
# 3000 → 13000
```

**预防措施**：
- 使用 `netstat` 或 `ss` 提前检查端口占用
- remotePort 避免使用常见端口（3000, 8080 等）
- 启动前执行清理脚本

### 问题 4：数据库连接失败

**现象**：`dial tcp 127.0.0.1:3306: connect: connection refused`

**根本原因**：
- 群晖 MariaDB 套件监听 **3307** 端口（非标准 3306）
- Gitea 默认尝试连接 3306

**解决方案**：

```bash
# 查看 MariaDB 实际端口
netstat -tuln | grep maria

# 方案 1：修改 Gitea 配置连接 3307
DB_TYPE = mysql
HOST = 127.0.0.1:3307

# 方案 2：改用 SQLite3（推荐个人使用）
DB_TYPE = sqlite3
```

**教训**：
- 群晖套件可能使用非标准端口
- 安装前务必确认服务实际配置
- 个人使用优先选择零配置方案

### 问题 5：多实例冲突

**现象**：`proxy [gitea-web] already exists`

**原因**：
- 多次启动脚本导致多个 frpc 进程
- 旧进程未清理干净

**解决方案**：

```bash
# 强制停止所有实例
kill -9 $(pgrep frpc)

# 或使用专用停止脚本
bash stop-all-frpc.sh
```

**预防措施**：
- 启动前先执行停止
- 使用进程管理工具（如 supervisor）
- 添加 PID 文件检查

## 安全配置

### 禁用公开注册

> [!warning] 重要安全设置
> 默认情况下，Gitea 允许任何人注册账号。对于个人 Git 服务，必须禁用此功能。

**方法 1：通过 Web 界面**

1. 以管理员登录 Gitea
2. 点击右上角头像 → **管理后台**
3. 左侧菜单 → **配置管理** → **服务管理**
4. 找到 **禁止用户自行注册** 并勾选
5. 点击 **保存配置**

**方法 2：修改配置文件**

编辑 `/var/packages/gitea/var/conf.ini`：

```ini
[service]
DISABLE_REGISTRATION = true
ENABLE_OPENID_SIGNUP = false
ALLOW_ONLY_EXTERNAL_REGISTRATION = false
```

### Token 管理

#### 创建访问令牌

1. 登录 Gitea → 右上角头像 → **设置**
2. 左侧菜单 → **应用** → **管理 Access Token**
3. 点击 **生成新的 Token**
4. 填写信息：
   - **令牌名称**：如 `sync-token`
   - **权限选择**：只勾选 `repo`（最小权限原则）
   - **过期时间**：建议 30-90 天
5. 点击 **生成令牌**
6. **⚠️ 立即复制 Token**（只显示一次）

#### Token 权限说明

| 权限范围 | 说明 | 个人使用 |
|---------|------|---------|
| `repo` | 仓库读写 | ✅ 必需 |
| `admin` | 管理员权限 | ❌ 不需要 |
| `user` | 用户信息 | ❌ 不需要 |
| `org` | 组织管理 | ❌ 不需要 |

#### Token 安全最佳实践

- ✅ **最小权限**：只授予必需的权限
- ✅ **定期更换**：每 3-6 个月更换一次
- ✅ **环境变量**：不要在脚本中硬编码 Token
- ✅ **监控使用**：定期检查 Token 使用记录
- ❌ **不要分享**：Token 相当于密码
- ❌ **不要提交**：不要提交到 Git 仓库

## 使用指南

### 日常操作

#### 启动 FRP 服务

```bash
bash /volume1/docker/frpc/start-frpc.sh
```

#### 停止 FRP 服务

```bash
bash /volume1/docker/frpc/stop-all-frpc.sh
```

#### 检查服务状态

```bash
bash /volume1/docker/frpc/status-frpc.sh
```

#### 查看日志

```bash
tail -f /var/log/frpc.log
```

#### 重启 Gitea

```bash
synopkg restart gitea
```

### Git 使用

#### HTTP 克隆

```bash
git clone https://git.haiguang.xyz/username/repo.git
```

#### SSH 克隆

```bash
git clone ssh://git@82.156.57.104:10022/username/repo.git
```

#### 配置 SSH 密钥

1. 生成密钥对：
```bash
ssh-keygen -t ed25519 -C "your_email@example.com"
```

2. 复制公钥到 Gitea：
```bash
cat ~/.ssh/id_ed25519.pub
# 在 Gitea → 设置 → SSH/GPG 密钥 → 添加密钥
```

3. 配置 SSH 客户端（`~/.ssh/config`）：
```
Host gitea-haiguang
    HostName 82.156.57.104
    Port 10022
    User git
    IdentityFile ~/.ssh/id_ed25519
```

4. 简化克隆：
```bash
git clone gitea-haiguang:username/repo.git
```

## 常用命令速查

```bash
# Gitea 相关
synopkg status gitea          # 查看状态
synopkg restart gitea         # 重启服务
synopkg stop gitea            # 停止服务
synopkg start gitea           # 启动服务

# FRP 相关
ps aux | grep frpc            # 查看进程
kill -9 $(pgrep frpc)         # 强制停止
tail -f /var/log/frpc.log     # 查看日志

# 网络诊断
netstat -tuln | grep 8418     # 检查端口
telnet 82.156.57.104 13000    # 测试连通性
curl -I https://git.haiguang.xyz/  # 测试 HTTP

# 数据库操作（SQLite3）
sqlite3 /var/packages/gitea/var/data/gitea.db ".tables"
sqlite3 /var/packages/gitea/var/data/gitea.db ".backup /tmp/gitea.db.bak"

# Git Token 配置
git remote set-url origin https://<token>@git.haiguang.xyz/username/repo.git
git remote -v                 # 验证配置
```

## 与 Gitea 故障排查的关系

本部署指南与 [[Gitea-故障排查]] 是互补关系：

| 维度 | 部署指南 | 故障排查 |
|------|---------|----------|
| **重点** | 部署流程、配置参数、架构设计 | 使用中遇到的具体问题 |
| **受众** | 从零搭建的人 | 已部署但遇到问题的人 |
| **内容** | 环境配置、脚本部署、安全设置 | 错误信息、解决方案、诊断命令 |
| **依赖** | 群晖 NAS、FRP 服务 | 部署完成的服务 |

**建议使用流程**：

1. 按照 [[Gitea 部署指南]] 完成部署
2. 遇到问题时，查阅 [[Gitea-故障排查]] 的对应章节
3. 使用本指南中的"常用命令速查"进行诊断

## 相关概念

- [[FRP]] - 内网穿透工具
- [[内网穿透]] - 将本地服务暴露到公网的技术
- [[Gitea]] - Git 托管服务本身
- [[群晖NAS]] - Synology 网络存储服务器
- [[Git]] - 版本控制系统

## 来源

- [[Gitea个人Git服务部署指南]] - 完整部署指南（2026-03-29）
- Gitea 官方文档：<https://docs.gitea.io/>
- FRP 官方文档：<https://gofrp.org/docs/>
- SynoCommunity 套件源：<https://github.com/SynoCommunity/spksrc>

[raw:Gitea个人Git服务部署指南:2]# Gitea 部署指南

> **一句话描述**：在群晖 NAS 上部署 Gitea + FRP 实现个人 Git 服务的公网访问

## 背景

在群晖 NAS 上部署 Gitea 代码仓库服务，通过 FRP 内网穿透暴露到公网，实现个人代码仓库的远程访问。相比 QuickConnect，FRP 提供更稳定的连接和更快的访问速度。

### 两种部署方案

| 方案 | 架构 | 优势 | 适用场景 |
|------|------|------|----------|
| **NAS 方案** | NAS + Gitea + FRP | 配置简单，无需额外 VPS | 已有 NAS，设备较少 |
| **VPS 方案** | VPS + Nginx + FRP + NAS + Gitea | HTTPS 自动化，可扩展多服务 | 需要独立域名，希望更稳定 |

**本指南重点**：NAS 方案（群晖 + Gitea + FRP）
**VPS 方案参考**：本指南后文的"VPS 方案"章节

---

## 环境概览

### 硬件环境

| 配置项 | 值 |
|--------|-----|
| NAS 型号 | Synology DS418play |
| CPU 架构 | Intel Celeron J3355 (x86_64) |
| 系统版本 | DSM 7.3.2-86009 Update 3 |
| 域名 | haiguang.xyz |

### 软件版本

| 软件 | 版本 | 说明 |
|------|------|------|
| Gitea | 1.25.5-28 | SynoCommunity 套件 |
| FRP | v0.68.0 | 最新版（2026-03-20 发布） |
| MariaDB | 10 | 群晖套件（监听 3307 端口） |

### 网络环境

| 服务 | 地址 |
|------|------|
| FRP 服务器 | 82.156.57.104:7000 |
| QuickConnect | hehaiguang.cn4.quickconnect.cn |
| 公网访问 | git.haiguang.xyz |

---

## 部署架构

### NAS 方案（本指南重点）

```mermaid
graph LR
    A[开发者] --> B[git.haiguang.xyz]
    B --> C[FRP服务器<br/>82.156.57.104]
    C --> D[FRP客户端<br/>群晖NAS]
    D --> E[Gitea服务<br/>端口8418]

    F[SSH访问] --> G[82.156.57.104:10022]
    G --> D
    D --> H[SSH服务<br/>端口10022]
```

**流量路径**：

1. **HTTP 访问**：`git.haiguang.xyz` → DNS 解析到 `82.156.57.104` → FRP 服务器端口 13000 → FRP 客户端 → Gitea 本地端口 8418
2. **SSH 访问**：`82.156.57.104:10022` → FRP 服务器 → FRP 客户端 → Gitea SSH 端口 10022

### VPS 方案（参考）

```mermaid
graph LR
    A[用户浏览器] -->|HTTPS| B[腾讯云VPS<br/>82.156.57.104]
    A -->|git clone/push| B
    B -->|Nginx反代| C[frps:13000]
    C -->|FRP隧道<br/>TLS加密| D[frpc]
    D -->|TCP| E[NAS Gitea:8418]
```

**VPS 端口映射**：

| 位置 | 端口 | 服务 |
|------|------|------|
| VPS | 7000 | frps 通信 |
| VPS | 13000 | frps 代理（Gitea Web） |
| VPS | 10022 | frps 代理（Gitea SSH） |
| VPS | 443 | Nginx HTTPS |
| VPS | 80 | Nginx HTTP → HTTPS |

---

## 方案选型

> [!tip] 选型结论
> 经过对比 Gitea vs Gogs、SQLite vs MySQL/PostgreSQL、FRP vs Tailscale，最终选择：**Gitea + SQLite + FRP**。

### Gitea vs Gogs vs GitLab

| 维度 | Gitea ✅ | Gogs | GitLab ❌ |
|------|---------|------|---------|
| 最低内存 | ~200MB | ~100MB | ≥4GB |
| 功能完整度 | PR/Actions/包管理/Wiki | 基础 | 全功能 |
| CI/CD | 内置 Actions | 需外接 | 内置 |
| 社区活跃度 | 非常活跃 | 维护模式 | 活跃 |

### 数据库选型

| 维度 | SQLite ✅ | MySQL | PostgreSQL | CouchDB（已有） |
|------|---------|-------|-----------|---------------|
| 额外内存 | 0 | ~200MB | ~200MB | ~43MB |
| 额外部署 | 无 | 需安装 | 需安装 | 已有 |
| Gitea 支持 | ✅ | ✅ | ✅ | ❌ |

### 内网穿透选型

| 维度 | FRP ✅ | Tailscale | Cloudflare Tunnel |
|------|--------|-----------|-------------------|
| 每台设备装客户端 | 不需要 | 需要 | 不需要 |
| 传输方式 | 中继 | P2P 优先 | 中继 |
| 部署复杂度 | 低 | 中 | 中 |
| 适用场景 | 少设备通用访问 | 多设备频繁访问 | HTTP-only |

> [!warning] Tailscale 不选的原因
> - 家宽 NAT 穿透不稳定，手机 4G 大概率走 DERP 中继（速度与 FRP 相当）
> - 每台设备都要装客户端，临时借用电脑不方便
> - VPS 带宽才是瓶颈（~2.8Mbps），P2P 优势有限

---

## VPS 方案部署（参考）

### VPS 环境信息

| 项目 | 值 |
|------|-----|
| 系统 | Ubuntu 24.04.4 LTS |
| CPU | 2 核 AMD EPYC 7K62 |
| 内存 | 2GB（可用约 640MB） |
| 磁盘 | 40GB（可用 14GB） |
| 公网 IP | 82.156.57.104 |
| 已有服务 | Nginx、OpenClaw Gateway、CouchDB |

### 第一步：FRP 服务端部署（VPS）

**1. 下载安装**

```bash
# 下载 FRP v0.68.0
wget https://github.com/fatedier/frp/releases/download/v0.68.0/frp_0.68.0_linux_amd64.tar.gz
tar -xzf frp_0.68.0_linux_amd64.tar.gz -C /opt/
mv /opt/frp_0.68.0_linux_amd64 /opt/frp
ln -s /opt/frp/frps /usr/local/bin/frps
```

**2. 配置 frps.toml**

```toml
# FRP 服务端配置
bindPort = 7000              # 客户端连接端口

[auth]
token = "你的强密码"           # 认证令牌（两端必须一致）

[transport]
tls.force = true             # 强制 TLS 加密

[webServer]
addr = "127.0.0.1"           # Dashboard 仅本地访问
port = 7500
user = "admin"
password = "你的密码"
```

**3. systemd 服务**

```ini
# /etc/systemd/system/frps.service
[Unit]
Description=FRP Server Service
After=network.target

[Service]
Type=simple
User=nobody
Restart=on-failure
RestartSec=5s
ExecStart=/usr/local/bin/frps -c /opt/frp/frps.toml

[Install]
WantedBy=multi-user.target
```

**4. 启动**

```bash
systemctl daemon-reload
systemctl enable --now frps
```

**5. 腾讯云安全组放行**

| 端口 | 协议 | 来源 | 用途 |
|------|------|------|------|
| 7000 | TCP | 0.0.0.0/0 | FRP 通信 |
| 13000 | TCP | 0.0.0.0/0 | Gitea Web |
| 10022 | TCP | 0.0.0.0/0 | Gitea SSH（可选） |

### 第二步：Nginx 反向代理 + HTTPS

**1. HTTP 反代配置**

```nginx
# /etc/nginx/sites-available/gitea
server {
    listen 80;
    listen [::]:80;
    server_name git.haiguang.xyz;

    access_log /var/log/nginx/gitea-access.log;
    error_log /var/log/nginx/gitea-error.log;

    location / {
        proxy_pass http://127.0.0.1:13000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        client_max_body_size 100m;
    }
}
```

**2. Let's Encrypt 证书**

```bash
# 安装 certbot
apt install certbot python3-certbot-nginx

# 签发证书并自动配置 HTTPS
certbot --nginx -d git.haiguang.xyz
```

certbot 会自动修改 Nginx 配置，添加 HTTPS 监听和证书路径。

### 第三步：FRP 客户端配置（NAS）

VPS 方案下的 FRP 客户端配置与 NAS 方案相同，见"部署步骤"章节。

### VPS 方案文件路径

| 文件 | 路径 |
|------|------|
| frps 二进制 | /usr/local/bin/frps |
| frps 配置 | /opt/frp/frps.toml |
| frps 服务 | /etc/systemd/system/frps.service |
| Nginx Gitea 配置 | /etc/nginx/sites-available/gitea |
| HTTPS 证书 | /etc/letsencrypt/live/git.haiguang.xyz/ |
| HTTPS 密钥 | /etc/letsencrypt/live/git.haiguang.xyz/privkey.pem |

---

## NAS 方案部署步骤

## 环境概览

### 硬件环境

| 配置项 | 值 |
|--------|-----|
| NAS 型号 | Synology DS418play |
| CPU 架构 | Intel Celeron J3355 (x86_64) |
| 系统版本 | DSM 7.3.2-86009 Update 3 |
| 域名 | haiguang.xyz |

### 软件版本

| 软件      | 版本        | 说明                 |
| ------- | --------- | ------------------ |
| Gitea   | 1.25.5-28 | SynoCommunity 套件   |
| FRP     | v0.68.0   | 最新版（2026-03-20 发布） |
| MariaDB | 10        | 群晖套件（监听 3307 端口）   |

### 网络环境

| 服务 | 地址 |
|------|------|
| FRP 服务器 | 82.156.57.104:7000 |
| QuickConnect | hehaiguang.cn4.quickconnect.cn |
| 公网访问 | git.haiguang.xyz |

## 部署架构

```mermaid
graph LR
    A[开发者] --> B[git.haiguang.xyz]
    B --> C[FRP服务器<br/>82.156.57.104]
    C --> D[FRP客户端<br/>群晖NAS]
    D --> E[Gitea服务<br/>端口8418]

    F[SSH访问] --> G[82.156.57.104:10022]
    G --> D
    D --> H[SSH服务<br/>端口10022]
```

### 流量路径

1. **HTTP 访问**：`git.haiguang.xyz` → DNS 解析到 `82.156.57.104` → FRP 服务器端口 13000 → FRP 客户端 → Gitea 本地端口 8418
2. **SSH 访问**：`82.156.57.104:10022` → FRP 服务器 → FRP 客户端 → Gitea SSH 端口 10022

## 部署步骤

### 第一阶段：Gitea 服务安装

#### 1. 安装 Gitea 套件

从 SynoCommunity 安装 Gitea 套件：

- 套件中心 → 设置 → 套件来源 → 新增
- 名称: SynoCommunity
- 位置: `https://packages.synocommunity.com/`
- 搜索并安装 Gitea

#### 2. 初始化配置

访问 `http://192.168.123.21:8418` 进行初始化：

**数据库配置**：

```
数据库类型: SQLite3
数据库文件: /var/packages/gitea/var/data/gitea.db
```

> [!tip] 数据库选择建议
> - **SQLite3**: 零配置，适合个人使用（≤50 仓库）
> - **MariaDB**: 性能更好，适合团队协作
> - 注意：群晖 MariaDB 监听 **3307** 端口（非标准 3306）

**应用配置**：

```
仓库存储路径: /volume3/gitea-share/gitea-repositories
管理员账号: giteahhg
密码: [你的密码]
```

### 第二阶段：FRP 客户端部署

#### 1. 配置文件 (frpc.toml)

```toml
serverAddr = "82.156.57.104"
serverPort = 7000
auth.method = "token"
auth.token = "deb19f52ac7fa6423efcd1a3fbf9c2b7"
transport.tls.enable = true
log.to = "/var/log/frpc.log"
log.level = "info"
log.maxDays = 7

[[proxies]]
name = "gitea-web"
type = "tcp"
localIP = "127.0.0.1"
localPort = 8418
remotePort = 13000

[[proxies]]
name = "gitea-ssh"
type = "tcp"
localIP = "127.0.0.1"
localPort = 10022
remotePort = 10022
```

> [!warning] 关键配置说明
> - **type**: 必须使用 `tcp`，HTTP 类型需要服务器配置 vhost
> - **localPort**: Gitea 实际运行端口（非标准 3000）
> - **remotePort**: 服务器开放端口，避免使用 3000（易冲突）

#### 2. 部署到群晖

将以下文件上传到群晖 `/volume1/docker/frpc/`：

- frpc.toml（配置文件）
- frp_0.68.0_linux_amd64.tar.gz（从 GitHub 下载）
- install-local.sh（安装脚本）
- start-frpc.sh（启动脚本）
- stop-all-frpc.sh（停止脚本）
- status-frpc.sh（状态检查）

#### 3. 执行部署

通过群晖任务计划执行：

```bash
# 安装 FRP
bash /volume1/docker/frpc/install-local.sh

# 启动客户端
bash /volume1/docker/frpc/start-frpc.sh

# 检查状态
bash /volume1/docker/frpc/status-frpc.sh
```

> [!danger] 常见错误：脚本执行失败
> **问题**: 任务计划执行后"标准输出/错误无内容"
> **原因**: Windows 换行符（CRLF）导致 bash 无法解析
> **解决**: 使用 `bash` 显式调用脚本，而非直接执行

### 第三阶段：配置更新

#### 1. 更新 ROOT_URL 和安全配置

编辑 `/var/packages/gitea/var/conf.ini`：

```ini
[server]
ROOT_URL = https://git.haiguang.xyz/
DOMAIN = git.haiguang.xyz
SSH_DOMAIN = git.haiguang.xyz

[service]
DISABLE_REGISTRATION = true          # 禁用公开注册
ENABLE_OPENID_SIGNUP = false
```

重启服务：

```bash
synopkg restart gitea
```

#### 2. 配置 DNS 解析

在域名服务商添加 A 记录：

| 类型 | 主机记录 | 记录值 | TTL |
|------|----------|--------|-----|
| A | git | 82.156.57.104 | 600 |

## 关键参数清单

### Gitea 配置

> [!important] 重要：配置文件路径
> 群晖 Gitea 套件的配置文件路径为：**`/var/packages/gitea/var/conf.ini`**
> 
> 很多文档错误地认为是 `/var/packages/gitea/var/app.ini`，这是不正确的。

| 参数 | 值 | 文件位置 |
|------|-----|----------|
| 本地端口 | 8418 | `/var/packages/gitea/var/conf.ini` |
| SSH 端口 | 10022 | 同上 |
| 数据库 | SQLite3 | `/var/packages/gitea/var/data/gitea.db` |
| 仓库目录 | `/volume3/gitea-share/gitea-repositories` | 初始化时设置 |
| ROOT_URL | `https://git.haiguang.xyz/` | 需手动更新 |
| 运行用户 | sc-gitea | 套件自动创建 |

### FRP 配置

| 参数 | 值 | 说明 |
|------|-----|------|
| 服务器地址 | 82.156.57.104 | FRP 服务器 IP |
| 服务器端口 | 7000 | FRP 服务端口 |
| 认证 Token | deb19f52ac7fa6423efcd1a3fbf9c2b7 | 服务端配置 |
| TLS 加密 | 启用 | 安全传输 |
| Web 代理 | 本地 8418 → 远程 13000 | TCP 模式 |
| SSH 代理 | 本地 10022 → 远程 10022 | TCP 模式 |

## 经验教训

### 问题 1：脚本执行失败

**现象**：群晖任务计划执行脚本后无输出，服务未启动

**根本原因**：
- Windows 环境创建的脚本使用 CRLF 换行符
- 群晖 bash 无法解析 CRLF 格式
- 直接执行 `./script.sh` 会静默失败

**解决方案**：

```bash
# 错误方式
./install-local.sh

# 正确方式
bash install-local.sh
```

**预防措施**：
- 使用 VSCode 统一换行符为 LF
- 或在脚本开头添加 `#!/bin/bash` 并用 bash 显式调用

### 问题 2：HTTP 代理不支持

**现象**：FRP 日志显示 `type [http] not supported`

**根本原因**：
- FRP 服务器未配置 `vhostHTTPPort`
- HTTP 类型代理需要服务端支持虚拟主机

**解决方案**：

改用 TCP 模式：

```toml
[[proxies]]
name = "gitea-web"
type = "tcp"  # 原为 "http"
localPort = 8418
remotePort = 13000
```

**对比**：

| 模式 | 优势 | 劣势 | 适用场景 |
|------|------|------|----------|
| HTTP | 支持域名路由，可共享 80 端口 | 需服务端配置 | 多服务共享域名 |
| TCP | 无需额外配置，通用性强 | 每服务需独立端口 | 单服务部署 |

### 问题 3：端口冲突

**现象**：Gitea 服务无法启动或 FRP 代理失败

**排查过程**：

1. 检查 Gitea 实际端口：`netstat -tuln | grep gitea` → 发现 8418
2. 检查 FRP 端口占用：`netstat -tuln | grep 3000` → VPS 已占用
3. 检查多实例：`ps aux | grep frpc` → 发现两个进程

**解决方案**：

```bash
# 清理所有 frpc 进程
kill -9 $(pgrep frpc)

# 修改 remotePort 为非标准端口
# 3000 → 13000
```

**预防措施**：
- 使用 `netstat` 或 `ss` 提前检查端口占用
- remotePort 避免使用常见端口（3000, 8080 等）
- 启动前执行清理脚本

### 问题 4：数据库连接失败

**现象**：`dial tcp 127.0.0.1:3306: connect: connection refused`

**根本原因**：
- 群晖 MariaDB 套件监听 **3307** 端口（非标准 3306）
- Gitea 默认尝试连接 3306

**解决方案**：

```bash
# 查看 MariaDB 实际端口
netstat -tuln | grep maria

# 方案 1：修改 Gitea 配置连接 3307
DB_TYPE = mysql
HOST = 127.0.0.1:3307

# 方案 2：改用 SQLite3（推荐个人使用）
DB_TYPE = sqlite3
```

**教训**：
- 群晖套件可能使用非标准端口
- 安装前务必确认服务实际配置
- 个人使用优先选择零配置方案

### 问题 5：多实例冲突

**现象**：`proxy [gitea-web] already exists`

**原因**：
- 多次启动脚本导致多个 frpc 进程
- 旧进程未清理干净

**解决方案**：

```bash
# 强制停止所有实例
kill -9 $(pgrep frpc)

# 或使用专用停止脚本
bash stop-all-frpc.sh
```

**预防措施**：
- 启动前先执行停止
- 使用进程管理工具（如 supervisor）
- 添加 PID 文件检查

## 安全配置

### 禁用公开注册

> [!warning] 重要安全设置
> 默认情况下，Gitea 允许任何人注册账号。对于个人 Git 服务，必须禁用此功能。

**方法 1：通过 Web 界面**

1. 以管理员登录 Gitea
2. 点击右上角头像 → **管理后台**
3. 左侧菜单 → **配置管理** → **服务管理**
4. 找到 **禁止用户自行注册** 并勾选
5. 点击 **保存配置**

**方法 2：修改配置文件**

编辑 `/var/packages/gitea/var/conf.ini`：

```ini
[service]
DISABLE_REGISTRATION = true
ENABLE_OPENID_SIGNUP = false
ALLOW_ONLY_EXTERNAL_REGISTRATION = false
```

### Token 管理

#### 创建访问令牌

1. 登录 Gitea → 右上角头像 → **设置**
2. 左侧菜单 → **应用** → **管理 Access Token**
3. 点击 **生成新的 Token**
4. 填写信息：
   - **令牌名称**：如 `sync-token`
   - **权限选择**：只勾选 `repo`（最小权限原则）
   - **过期时间**：建议 30-90 天
5. 点击 **生成令牌**
6. **⚠️ 立即复制 Token**（只显示一次）

#### Token 权限说明

| 权限范围 | 说明 | 个人使用 |
|---------|------|---------|
| `repo` | 仓库读写 | ✅ 必需 |
| `admin` | 管理员权限 | ❌ 不需要 |
| `user` | 用户信息 | ❌ 不需要 |
| `org` | 组织管理 | ❌ 不需要 |

#### Token 安全最佳实践

- ✅ **最小权限**：只授予必需的权限
- ✅ **定期更换**：每 3-6 个月更换一次
- ✅ **环境变量**：不要在脚本中硬编码 Token
- ✅ **监控使用**：定期检查 Token 使用记录
- ❌ **不要分享**：Token 相当于密码
- ❌ **不要提交**：不要提交到 Git 仓库

## 使用指南

### 日常操作

#### 启动 FRP 服务

```bash
bash /volume1/docker/frpc/start-frpc.sh
```

#### 停止 FRP 服务

```bash
bash /volume1/docker/frpc/stop-all-frpc.sh
```

#### 检查服务状态

```bash
bash /volume1/docker/frpc/status-frpc.sh
```

#### 查看日志

```bash
tail -f /var/log/frpc.log
```

#### 重启 Gitea

```bash
synopkg restart gitea
```

### Git 使用

#### HTTP 克隆

```bash
git clone https://git.haiguang.xyz/username/repo.git
```

#### SSH 克隆

```bash
git clone ssh://git@82.156.57.104:10022/username/repo.git
```

#### 配置 SSH 密钥

1. 生成密钥对：
```bash
ssh-keygen -t ed25519 -C "your_email@example.com"
```

2. 复制公钥到 Gitea：
```bash
cat ~/.ssh/id_ed25519.pub
# 在 Gitea → 设置 → SSH/GPG 密钥 → 添加密钥
```

3. 配置 SSH 客户端（`~/.ssh/config`）：
```
Host gitea-haiguang
    HostName 82.156.57.104
    Port 10022
    User git
    IdentityFile ~/.ssh/id_ed25519
```

4. 简化克隆：
```bash
git clone gitea-haiguang:username/repo.git
```

## 常用命令速查

```bash
# Gitea 相关
synopkg status gitea          # 查看状态
synopkg restart gitea         # 重启服务
synopkg stop gitea            # 停止服务
synopkg start gitea           # 启动服务

# FRP 相关
ps aux | grep frpc            # 查看进程
kill -9 $(pgrep frpc)         # 强制停止
tail -f /var/log/frpc.log     # 查看日志

# 网络诊断
netstat -tuln | grep 8418     # 检查端口
telnet 82.156.57.104 13000    # 测试连通性
curl -I https://git.haiguang.xyz/  # 测试 HTTP

# 数据库操作（SQLite3）
sqlite3 /var/packages/gitea/var/data/gitea.db ".tables"
sqlite3 /var/packages/gitea/var/data/gitea.db ".backup /tmp/gitea.db.bak"

# Git Token 配置
git remote set-url origin https://<token>@git.haiguang.xyz/username/repo.git
git remote -v                 # 验证配置
```

## 与 Gitea 故障排查的关系

本部署指南与 [[Gitea-故障排查]] 是互补关系：

| 维度 | 部署指南 | 故障排查 |
|------|---------|----------|
| **重点** | 部署流程、配置参数、架构设计 | 使用中遇到的具体问题 |
| **受众** | 从零搭建的人 | 已部署但遇到问题的人 |
| **内容** | 环境配置、脚本部署、安全设置 | 错误信息、解决方案、诊断命令 |
| **依赖** | 群晖 NAS、FRP 服务 | 部署完成的服务 |

**建议使用流程**：

1. 按照 [[Gitea 部署指南]] 完成部署
2. 遇到问题时，查阅 [[Gitea-故障排查]] 的对应章节
3. 使用本指南中的"常用命令速查"进行诊断

## 相关概念

- [[FRP]] - 内网穿透工具
- [[内网穿透]] - 将本地服务暴露到公网的技术
- [[Gitea]] - Git 托管服务本身
- [[群晖NAS]] - Synology 网络存储服务器
- [[Git]] - 版本控制系统

## 来源

- [[Gitea个人Git服务部署指南]] - 完整部署指南（2026-03-29）
- Gitea 官方文档：<https://docs.gitea.io/>
- FRP 官方文档：<https://gofrp.org/docs/>
- SynoCommunity 套件源：<https://github.com/SynoCommunity/spksrc>