giteahh/llm_wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b101b6516c94a0761d6cdcf288654194347473ad
llm_wiki/wiki/Gitea-部署指南.md
T

39 KiB
Raw Blame History

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

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

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

背景

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

两种部署方案

| 方案 | 架构 | 优势 | 适用场景 |
------
NAS 方案
VPS 方案

本指南重点：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 方案（本指南重点）

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 方案（参考）

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. 下载安装

# 下载 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

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

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

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

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

3. systemd 服务

# /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. 启动

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 反代配置

# /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 证书

# 安装 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

部署架构

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)

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 显式调用脚本，而非直接执行

第三阶段：配置更新

1. 更新 ROOT_URL 和安全配置

编辑 /var/packages/gitea/var/conf.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

重启服务：

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

解决方案：

# 错误方式
./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

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 /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"
  1. 复制公钥到 Gitea：
cat ~/.ssh/id_ed25519.pub
# 在 Gitea → 设置 → SSH/GPG 密钥 → 添加密钥
  1. 配置 SSH 客户端（~/.ssh/config）：
Host gitea-haiguang
    HostName 82.156.57.104
    Port 10022
    User git
    IdentityFile ~/.ssh/id_ed25519
  1. 简化克隆：
git clone gitea-haiguang:username/repo.git

常用命令速查

# 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 - 版本控制系统

来源

[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 方案（本指南重点）

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 方案（参考）

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. 下载安装

# 下载 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

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

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

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

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

3. systemd 服务

# /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. 启动

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 反代配置

# /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 证书

# 安装 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

部署架构

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)

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 显式调用脚本，而非直接执行

第三阶段：配置更新

1. 更新 ROOT_URL 和安全配置

编辑 /var/packages/gitea/var/conf.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

重启服务：

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

解决方案：

# 错误方式
./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

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 /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"
  1. 复制公钥到 Gitea：
cat ~/.ssh/id_ed25519.pub
# 在 Gitea → 设置 → SSH/GPG 密钥 → 添加密钥
  1. 配置 SSH 客户端（~/.ssh/config）：
Host gitea-haiguang
    HostName 82.156.57.104
    Port 10022
    User git
    IdentityFile ~/.ssh/id_ed25519
  1. 简化克隆：
git clone gitea-haiguang:username/repo.git

常用命令速查

# 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 - 版本控制系统

来源

Reference in New Issue View Git Blame Copy Permalink