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

title, created, tags, aliases

title	created	tags	aliases
Gitea个人Git服务部署指南	2026-03-29	群晖 Gitea FRP 内网穿透 Git	自建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

---

部署架构

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. 确认服务状态

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

# 查看服务状态
synopkg status gitea

第二阶段：FRP客户端部署

1. 准备部署文件

在本地创建以下文件：

frpc.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. 执行部署

通过群晖任务计划执行：

# 安装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. 验证连接

# 查看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：

#!/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 /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 会静默失败

解决方案：

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

# 正确方式
bash install-local.sh

预防措施：

• 使用VSCode统一换行符为LF
• 或在脚本开头添加 #!/bin/bash 并用bash显式调用

---

问题2：HTTP代理不支持

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

根本原因：

• FRP服务器未配置 vhostHTTPPort
• HTTP类型代理需要服务端支持虚拟主机

解决方案：

改用TCP模式：

[[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 → 发现两个进程

解决方案：

# 清理所有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

解决方案：

# 查看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进程
• 旧进程未清理干净

解决方案：

# 强制停止所有实例
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：

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

重启服务：

synopkg restart gitea

---

Token管理

创建访问令牌

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

配置Git使用Token

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)：

# 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. 在属性中设置每小时重复

查看同步日志

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

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

---

完整配置示例

Gitea配置文件（完整版）

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配置文件（完整版）

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 /volume1/docker/frpc/start-frpc.sh

停止FRP服务

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

检查服务状态

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

查看日志

tail -f /var/log/frpc.log

重启Gitea

synopkg restart gitea

---

Git使用

HTTP克隆

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

SSH克隆

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

配置SSH密钥

1. 生成密钥对：

ssh-keygen -t ed25519 -C "your_email@example.com"

2. 复制公钥到Gitea：

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. 简化克隆：

git clone gitea-haiguang:username/repo.git

---

维护任务

定期备份

创建群晖任务计划，每周执行：

#!/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：

#!/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分钟执行：

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

---

故障排查

无法访问git.haiguang.xyz

排查步骤：

1. 检查DNS解析：

nslookup git.haiguang.xyz
# 应返回 82.156.57.104

2. 检查FRP客户端状态：

ps aux | grep frpc
tail -f /var/log/frpc.log

3. 检查服务器端口：

telnet 82.156.57.104 13000

4. 检查Gitea服务：

synopkg status gitea
curl http://127.0.0.1:8418

---

SSH连接失败

排查步骤：

1. 检查SSH服务：

netstat -tuln | grep 10022

2. 检查SSH密钥：

ssh -v git@82.156.57.104 -p 10022

3. 检查Gitea SSH配置：

[server]
START_SSH_SERVER = true
SSH_PORT = 10022

---

推送超时

可能原因：

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

解决方案：

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

---

参考资源

官方文档

• [Gitea官方文档]
• [FRP官方文档]
• [SynoCommunity套件源]

相关笔记

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

---

变更记录

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

---

附录

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. 常用命令速查

# 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 `
配置不生效	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换行符、端口冲突、数据库配置等实际问题。最终实现了稳定的公网访问，为个人代码管理提供了可靠的基础设施。