llm_wiki/raw/Gitea个人Git服务部署指南.md

---
title: Gitea个人Git服务部署指南
created: 2026-03-29
tags:
  - 群晖
  - Gitea
  - FRP
  - 内网穿透
  - Git
aliases:
  - 自建Git服务
  - NAS代码仓库
---

# Gitea个人Git服务部署指南

## 项目背景

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

---

## 环境信息

### 硬件环境

| 配置项 | 值 |
|--------|-----|
| 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
密码: [你的密码]
```

#### 3. 确认服务状态

```bash
# 查看运行端口
netstat -tuln | grep gitea

# 查看服务状态
synopkg status gitea
```

### 第二阶段：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` 显式调用脚本，而非直接执行

#### 4. 验证连接

```bash
# 查看FRP进程
ps aux | grep frpc

# 查看日志
tail -f /var/log/frpc.log

# 预期输出
# [gitea-web] start proxy success
# [gitea-ssh] start proxy success
```

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

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

创建更新脚本 `update-gitea-security.sh`：

```bash
#!/bin/bash
CONFIG_FILE="/var/packages/gitea/var/conf.ini"

# 备份配置
cp "$CONFIG_FILE" "${CONFIG_FILE}.backup.$(date +%Y%m%d_%H%M%S)"

# 更新访问URL
sed -i 's|^ROOT_URL.*|ROOT_URL = https://git.haiguang.xyz/|' "$CONFIG_FILE"
sed -i 's|^DOMAIN.*|DOMAIN = git.haiguang.xyz|' "$CONFIG_FILE"
sed -i 's|^SSH_DOMAIN.*|SSH_DOMAIN = git.haiguang.xyz|' "$CONFIG_FILE"

# 安全加固：禁用公开注册
sed -i 's|^DISABLE_REGISTRATION.*|DISABLE_REGISTRATION = true|' "$CONFIG_FILE"
sed -i 's|^ENABLE_OPENID_SIGNUP.*|ENABLE_OPENID_SIGNUP = false|' "$CONFIG_FILE"

# 重启服务
synopkg restart gitea

echo "配置更新完成！访问: https://git.haiguang.xyz/"
```

执行：

```bash
bash /volume1/docker/frpc/update-gitea-security.sh
```

#### 2. 配置DNS解析

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

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

#### 3. 配置开机自启

创建群晖任务计划：

- 控制面板 → 任务计划 → 新增 → 触发的任务 → 用户定义的脚本
- 事件: 开机
- 用户: root
- 脚本: `bash /volume1/docker/frpc/start-frpc.sh`

---

## 关键参数清单

### 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
```

重启服务：

```bash
synopkg restart gitea
```

---

### Token管理

#### 创建访问令牌

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

#### 配置Git使用Token

```bash
cd /path/to/your/repo
git remote set-url origin https://<token>@git.haiguang.xyz/username/repo.git
```

#### Token权限说明

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

#### Token安全最佳实践

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

---

### 自动同步配置

#### 创建同步脚本

**PowerShell版本** (`sync-gitea.ps1`)：

```powershell
# Gitea仓库自动同步脚本
param(
    [string]$RepoPath = "D:\TC_UP\2023card\projects\openclaw\obsidian_claw",
    [string]$LogFile = "D:\TC_UP\2023card\projects\openclaw\obsidian_claw\sync.log",
    [switch]$Quiet
)

function Write-Log {
    param([string]$Message)
    $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
    $logEntry = "[$timestamp] $Message"
    Add-Content -Path $LogFile -Value $logEntry
    if (-not $Quiet) { Write-Host $logEntry }
}

try {
    Write-Log "开始同步"
    Push-Location $RepoPath
    
    # 检查本地更改
    $changes = git status --porcelain
    if ($changes.Count -gt 0) {
        Write-Log "提交本地更改"
        git add -A
        git commit -m "自动同步: $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')"
    }
    
    # 拉取和推送
    Write-Log "拉取远程更改"
    git pull
    
    if ($changes.Count -gt 0) {
        Write-Log "推送本地更改"
        git push
    }
    
    Pop-Location
    Write-Log "同步完成"
} catch {
    Write-Log "错误: $_"
    exit 1
}
```

#### 配置Windows任务计划

1. 打开任务计划程序（`taskschd.msc`）
2. 创建基本任务：
   - 名称：`Gitea仓库同步`
   - 触发器：每天
   - 操作：启动程序
   - 程序：`powershell.exe`
   - 参数：`-ExecutionPolicy Bypass -File "D:\path\to\sync-gitea.ps1" -Quiet`
3. 在属性中设置每小时重复

#### 查看同步日志

```powershell
# 查看最近20条日志
Get-Content sync.log -Tail 20

# 监控日志
Get-Content sync.log -Wait
```

---

## 完整配置示例

### Gitea配置文件（完整版）

```ini
APP_NAME = Gitea: Git with a cup of tea
RUN_USER = sc-gitea
WORK_PATH = /var/packages/gitea/var
RUN_MODE = prod

[repository]
ROOT = /volume3/gitea-share/gitea-repositories

[server]
SSH_DOMAIN = git.haiguang.xyz
DOMAIN = git.haiguang.xyz
ROOT_URL = https://git.haiguang.xyz/
LOCAL_ROOT_URL = http://localhost:8418/
HTTP_PORT = 8418
APP_DATA_PATH = /var/packages/gitea/var/data
DISABLE_SSH = false
SSH_PORT = 10022
LFS_START_SERVER = true
OFFLINE_MODE = true

[lfs]
PATH = /volume3/gitea-share/lfs

[database]
DB_TYPE = sqlite3
PATH = /var/packages/gitea/var/data/gitea.db

[service]
REGISTER_EMAIL_CONFIRM = false
ENABLE_NOTIFY_MAIL = false
DISABLE_REGISTRATION = true          # 禁用公开注册
ALLOW_ONLY_EXTERNAL_REGISTRATION = false
ENABLE_CAPTCHA = false
REQUIRE_SIGNIN_VIEW = false
DEFAULT_KEEP_EMAIL_PRIVATE = false
DEFAULT_ALLOW_CREATE_ORGANIZATION = true
DEFAULT_ENABLE_TIMETRACKING = true

[openid]
ENABLE_OPENID_SIGNIN = true
ENABLE_OPENID_SIGNUP = false         # 禁用OpenID注册

[security]
INSTALL_LOCK = true
PASSWORD_HASH_ALGO = pbkdf2

[log]
MODE = console
LEVEL = info
ROOT_PATH = /var/packages/gitea/var/log
```

### FRP配置文件（完整版）

```toml
serverAddr = "82.156.57.104"
serverPort = 7000
auth.method = "token"
auth.token = "your-token-here"
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
```

---

## 使用指南

### 日常操作

#### 启动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
#!/bin/bash
BACKUP_DIR="/volume1/backup/gitea"
DATE=$(date +%Y%m%d)

# 备份数据库
sqlite3 /var/packages/gitea/var/data/gitea.db ".backup ${BACKUP_DIR}/gitea-${DATE}.db"

# 备份配置
cp /var/packages/gitea/var/app.ini ${BACKUP_DIR}/app.ini.${DATE}

# 备份仓库（增量）
rsync -av /volume3/gitea-share/gitea-repositories/ ${BACKUP_DIR}/repos/

# 清理30天前的备份
find ${BACKUP_DIR} -name "*.db" -mtime +30 -delete
```

#### 监控脚本

创建 `check-gitea-health.sh`：

```bash
#!/bin/bash
# 检查Gitea服务
if ! synopkg status gitea | grep -q "start"; then
    synopkg restart gitea
    echo "$(date) Gitea服务重启" >> /var/log/gitea-health.log
fi

# 检查FRP客户端
if ! pgrep -x "frpc" > /dev/null; then
    bash /volume1/docker/frpc/start-frpc.sh
    echo "$(date) FRP客户端重启" >> /var/log/gitea-health.log
fi
```

配置cron每5分钟执行：

```bash
*/5 * * * * bash /volume1/docker/frpc/check-gitea-health.sh
```

---

## 故障排查

### 无法访问git.haiguang.xyz

**排查步骤**：

1. 检查DNS解析：
```bash
nslookup git.haiguang.xyz
# 应返回 82.156.57.104
```

2. 检查FRP客户端状态：
```bash
ps aux | grep frpc
tail -f /var/log/frpc.log
```

3. 检查服务器端口：
```bash
telnet 82.156.57.104 13000
```

4. 检查Gitea服务：
```bash
synopkg status gitea
curl http://127.0.0.1:8418
```

---

### SSH连接失败

**排查步骤**：

1. 检查SSH服务：
```bash
netstat -tuln | grep 10022
```

2. 检查SSH密钥：
```bash
ssh -v git@82.156.57.104 -p 10022
```

3. 检查Gitea SSH配置：
```ini
[server]
START_SSH_SERVER = true
SSH_PORT = 10022
```

---

### 推送超时

**可能原因**：

- 网络带宽不足
- 仓库过大
- FRP超时配置过短

**解决方案**：

```toml
# frpc.toml 增加超时时间
transport.dialTimeout = 30
transport.poolCount = 5
```

---

## 参考资源

### 官方文档

- [[Gitea官方文档]](https://docs.gitea.io/)
- [[FRP官方文档]](https://gofrp.org/docs/)
- [[SynoCommunity套件源]](https://github.com/SynoCommunity/spksrc)

### 相关笔记

- [[群晖NAS配置指南]]
- [[FRP内网穿透原理]]
- [[Git最佳实践]]

---

## 变更记录

| 日期 | 版本 | 变更内容 |
|------|------|----------|
| 2026-03-29 | 1.0 | 初始版本，记录完整部署流程 |
| 2026-03-29 | 1.1 | 新增内容：<br>- 修正配置文件路径（conf.ini而非app.ini）<br>- 添加安全配置章节（禁用注册、Token管理）<br>- 添加自动同步脚本配置<br>- 完善配置示例和故障排查清单<br>- 新增关键配置路径对照表 |

---

## 附录

### A. 部署文件清单

```
/volume1/docker/frpc/
├── frp_0.68.0_linux_amd64/        # FRP程序目录
│   ├── frpc                       # 客户端程序
│   └── frpc.toml                  # 配置文件
├── frp_0.68.0_linux_amd64.tar.gz  # 安装包
├── install-local.sh               # 安装脚本
├── start-frpc.sh                  # 启动脚本
├── stop-all-frpc.sh               # 停止脚本
├── status-frpc.sh                 # 状态检查
├── check-gitea-health.sh          # 健康检查
└── update-gitea-security.sh       # 配置更新

/var/packages/gitea/var/
├── conf.ini                       # Gitea配置文件（重要）
├── data/
│   └── gitea.db                   # SQLite数据库
└── log/                           # 日志目录

本地Windows仓库（obsidian_claw）/
├── sync-gitea.bat                 # 同步脚本（BAT版）
├── sync-gitea.ps1                 # 同步脚本（PowerShell版）
├── 同步脚本使用说明.md            # 同步脚本文档
└── sync.log                       # 同步日志
```

### B. 服务端口映射表

| 服务 | 本地地址 | 远程地址 | 协议 |
|------|----------|----------|------|
| Gitea Web | 127.0.0.1:8418 | 82.156.57.104:13000 | TCP |
| Gitea SSH | 127.0.0.1:10022 | 82.156.57.104:10022 | TCP |

### C. 常用命令速查

```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                 # 验证配置

# Windows同步脚本
powershell -ExecutionPolicy Bypass -File sync-gitea.ps1
Get-Content sync.log -Tail 20 # 查看日志
```

### D. 故障排查清单

| 问题 | 检查命令 | 解决方案 |
|------|---------|---------|
| 无法访问仓库 | `curl -I https://git.haiguang.xyz/` | 检查DNS、FRP、Gitea服务 |
| Git推送失败 | `git remote -v` | 检查Token是否有效 |
| FRP连接失败 | `tail -f /var/log/frpc.log` | 检查服务器状态、Token |
| 脚本执行失败 | 使用 `bash script.sh` | 检查换行符（LF vs CRLF） |
| 端口冲突 | `netstat -tuln | grep <port>` | 修改端口号 |
| 配置不生效 | `synopkg restart gitea` | 重启服务 |

### E. 关键配置路径对照表

| 配置项 | 路径 | 说明 |
|--------|------|------|
| Gitea配置 | `/var/packages/gitea/var/conf.ini` | ⚠️ 不是app.ini |
| 数据库文件 | `/var/packages/gitea/var/data/gitea.db` | SQLite3 |
| FRP配置 | `/volume1/docker/frpc/frpc.toml` | TOML格式 |
| FRP日志 | `/var/log/frpc.log` | 按maxDays轮转 |
| 仓库目录 | `/volume3/gitea-share/gitea-repositories/` | 初始化时设置 |
| LFS文件 | `/volume3/gitea-share/lfs/` | 大文件存储 |

---

> [!quote] 总结
> 本次部署从零开始搭建了完整的个人Git服务，涵盖了Gitea安装、FRP内网穿透、域名配置、SSH密钥管理等核心环节。通过群晖任务计划实现了无SSH的远程部署，解决了Windows换行符、端口冲突、数据库配置等实际问题。最终实现了稳定的公网访问，为个人代码管理提供了可靠的基础设施。