Phase 0-2: Schema cleanup, typed relations, event-driven automation
- Phase 0: AGENTS.md cleanup (dedup quotes, renumber sections, merge qmd) - Phase 1: typed relations (manage-relations.py, graph-search.py, check-staleness.py, detect-conflicts.py) - Phase 2: frontmatter validator, weekly lint, knowledge promotion, git hooks - Fix .gitignore to track tools/ and .githooks/ - Fix git remote URL (remove plaintext token) - New wiki pages: 504 pages, 34 raw sources
This commit is contained in:
hehaiguang1123
@@ -0,0 +1,447 @@
|
||||
---
|
||||
title: 个人Git服务部署指南
|
||||
date: 2026-03-29
|
||||
tags:
|
||||
- git
|
||||
- gitea
|
||||
- frp
|
||||
- nginx
|
||||
- 运维
|
||||
aliases:
|
||||
- Git服务部署
|
||||
- FRP内网穿透
|
||||
- Gitea安装
|
||||
---
|
||||
|
||||
# 个人Git服务部署指南
|
||||
|
||||
> 基于 FRP 内网穿透 + Gitea + Nginx 反代 + Let's Encrypt HTTPS 的完整个人 Git 服务方案。内网群晖 NAS 运行 Gitea，通过腾讯云 VPS 中转暴露到公网。
|
||||
|
||||
## 架构概览
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[用户浏览器] -->|HTTPS| B[腾讯云VPS]
|
||||
A -->|git clone/push| B
|
||||
B -->|Nginx反代| C[frps:13000]
|
||||
C -->|FRP隧道<br/>TLS加密| D[frpc]
|
||||
D -->|TCP| E[NAS Gitea:8418]
|
||||
```
|
||||
|
||||
## 环境信息
|
||||
|
||||
### VPS（腾讯云轻量应用服务器）
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|-----|
|
||||
| 系统 | Ubuntu 24.04.4 LTS |
|
||||
| CPU | 2核 AMD EPYC 7K62 |
|
||||
| 内存 | 2GB（可用约640MB） |
|
||||
| 磁盘 | 40GB（可用14GB） |
|
||||
| 公网IP | 82.156.57.104 |
|
||||
| 已有服务 | Nginx、OpenClaw Gateway、CouchDB |
|
||||
|
||||
### NAS（群晖）
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|-----|
|
||||
| 内网IP | 192.168.123.21 |
|
||||
| Gitea端口 | 8418 |
|
||||
| Gitea SSH端口 | 10022 |
|
||||
| FRP客户端 | frpc v0.68.0 |
|
||||
|
||||
### 域名
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|-----|
|
||||
| 域名 | git.haiguang.xyz |
|
||||
| DNS服务商 | 腾讯云 |
|
||||
| 记录类型 | A 记录 → 82.156.57.104 |
|
||||
| HTTPS | Let's Encrypt（自动续期） |
|
||||
|
||||
---
|
||||
|
||||
## 部署过程
|
||||
|
||||
### 第一步：方案选型
|
||||
|
||||
> [!tip] 选型结论
|
||||
> 经过对比 Gitea vs Gogs、SQLite vs MySQL/PostgreSQL、FRP vs Tailscale，最终选择：**Gitea + SQLite + FRP**。
|
||||
|
||||
**对比记录：**
|
||||
|
||||
| 维度 | 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优势有限
|
||||
|
||||
### 第二步：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（可选） |
|
||||
|
||||
### 第三步：FRP 客户端配置（NAS）
|
||||
|
||||
```toml
|
||||
serverAddr = "82.156.57.104"
|
||||
serverPort = 7000
|
||||
auth.method = "token"
|
||||
auth.token = "你的token"
|
||||
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
|
||||
```
|
||||
|
||||
### 第四步：DNS 解析
|
||||
|
||||
在腾讯云 DNS 解析添加：
|
||||
|
||||
| 类型 | 主机记录 | 记录值 |
|
||||
|------|---------|--------|
|
||||
| A | git | 82.156.57.104 |
|
||||
|
||||
> [!warning] 域名注意事项
|
||||
> - 确认域名 DNS 服务器是腾讯云 DNSPod（ns1/ns2.dnspod.net）
|
||||
> - 如果用了第三方 DNS（如加速乐），在腾讯云加的记录不会生效
|
||||
> - `haiguang.com` 用了加速乐 DNS，改用 `haiguang.xyz` 解决
|
||||
|
||||
### 第五步：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 监听和证书路径。
|
||||
|
||||
### 第六步：Gitea 初始化
|
||||
|
||||
通过 `https://git.haiguang.xyz` 访问，完成初始设置：
|
||||
|
||||
- 数据库：**SQLite**（无需额外部署）
|
||||
- ROOT_URL：`https://git.haiguang.xyz/`
|
||||
- 禁止公开注册
|
||||
- 设置管理员账号
|
||||
|
||||
---
|
||||
|
||||
## 关键参数速查
|
||||
|
||||
### 端口映射
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph VPS ["腾讯云 VPS (82.156.57.104)"]
|
||||
A[":7000 frps通信"]
|
||||
B[":13000 → Gitea Web"]
|
||||
C[":10022 → Gitea SSH"]
|
||||
D[":443 Nginx HTTPS"]
|
||||
E[":80 Nginx HTTP→HTTPS"]
|
||||
D -->|反代| B
|
||||
end
|
||||
|
||||
subgraph NAS ["群晖 NAS (192.168.123.21)"]
|
||||
F["frpc"]
|
||||
G[":8418 Gitea Web"]
|
||||
H[":10022 Gitea SSH"]
|
||||
F -->|隧道| A
|
||||
B -->|穿透| G
|
||||
C -->|穿透| H
|
||||
end
|
||||
```
|
||||
|
||||
| 位置 | 端口 | 服务 | 说明 |
|
||||
|------|------|------|------|
|
||||
| VPS | 7000 | frps | FRP通信（必须开放） |
|
||||
| VPS | 13000 | frps代理 | Gitea Web穿透端口 |
|
||||
| VPS | 10022 | frps代理 | Gitea SSH穿透端口 |
|
||||
| VPS | 80/443 | Nginx | 对外HTTPS访问 |
|
||||
| NAS | 8418 | Gitea | Web服务 |
|
||||
| NAS | 10022 | Gitea | SSH服务 |
|
||||
|
||||
### 文件路径
|
||||
|
||||
| 文件 | 路径 |
|
||||
|------|------|
|
||||
| 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 |
|
||||
|
||||
### 认证信息
|
||||
|
||||
> [!danger] 敏感信息，注意保密
|
||||
|
||||
| 项目 | 值 | 说明 |
|
||||
|------|-----|------|
|
||||
| frps auth.token | deb***c2b7 | FRP通信认证 |
|
||||
| frps TLS | 强制开启 | 传输加密 |
|
||||
| Dashboard | 127.0.0.1:7500 | 仅本地访问 |
|
||||
|
||||
---
|
||||
|
||||
## 使用指南
|
||||
|
||||
### 通过浏览器访问
|
||||
|
||||
直接打开 **<https://git.haiguang.xyz>** 即可。
|
||||
|
||||
### 通过 Git 命令行
|
||||
|
||||
```bash
|
||||
# HTTPS 方式（推荐，无需端口）
|
||||
git clone https://git.haiguang.xyz/username/repo.git
|
||||
git push origin main
|
||||
|
||||
# SSH 方式（需配置端口10022）
|
||||
git clone ssh://git@git.haiguang.xyz:10022/username/repo.git
|
||||
```
|
||||
|
||||
### 配置 Git SSH（可选）
|
||||
|
||||
```bash
|
||||
# 生成密钥
|
||||
ssh-keygen -t ed25519 -C "your@email.com"
|
||||
|
||||
# 添加到 Gitea → 设置 → SSH/GPG Keys
|
||||
|
||||
# 测试连接
|
||||
ssh -T -p 10022 git@git.haiguang.xyz
|
||||
```
|
||||
|
||||
### 添加远程仓库（已有项目迁移）
|
||||
|
||||
```bash
|
||||
cd existing-project
|
||||
git remote add origin https://git.haiguang.xyz/username/repo.git
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 日常维护
|
||||
|
||||
### 检查服务状态
|
||||
|
||||
```bash
|
||||
# FRP服务端
|
||||
systemctl status frps
|
||||
|
||||
# FRP客户端连接日志
|
||||
journalctl -u frps --no-pager -n 20
|
||||
|
||||
# Nginx
|
||||
/usr/sbin/nginx -t
|
||||
|
||||
# 证书到期检查
|
||||
certbot certificates
|
||||
```
|
||||
|
||||
### 常见问题排查
|
||||
|
||||
> [!bug] frpc 连接失败
|
||||
> 1. 检查腾讯云安全组是否放行 7000 端口
|
||||
> 2. 检查 frpc 的 token 是否与 frps 一致
|
||||
> 3. 检查 `transport.tls.enable` 是否开启
|
||||
> 4. 查看 frpc 日志：`cat /var/log/frpc.log`
|
||||
|
||||
> [!bug] proxy already exists
|
||||
> 旧连接未断开，重启 frps 解决：`systemctl restart frps`
|
||||
|
||||
> [!bug] Gitea 页面链接错误
|
||||
> 检查 `app.ini` 中 `ROOT_URL` 是否设为 `https://git.haiguang.xyz/`
|
||||
|
||||
> [!bug] Git clone/push 失败
|
||||
> 1. HTTPS 方式：检查证书是否有效，防火墙是否放行 443
|
||||
> 2. SSH 方式：检查端口 10022 是否放行，SSH 密钥是否添加
|
||||
|
||||
### 证书续期
|
||||
|
||||
certbot 已自动配置续期，无需手动操作。可以手动测试：
|
||||
|
||||
```bash
|
||||
certbot renew --dry-run
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 扩展：穿透更多服务
|
||||
|
||||
在 NAS 的 frpc.toml 中添加新的 `[[proxies]]` 即可：
|
||||
|
||||
```toml
|
||||
# 示例：穿透群晖 WebDAV
|
||||
[[proxies]]
|
||||
name = "webdav"
|
||||
type = "tcp"
|
||||
localIP = "127.0.0.1"
|
||||
localPort = 5005
|
||||
remotePort = 13001
|
||||
|
||||
# 示例：穿透 Jellyfin
|
||||
[[proxies]]
|
||||
name = "jellyfin"
|
||||
type = "tcp"
|
||||
localIP = "127.0.0.1"
|
||||
localPort = 8096
|
||||
remotePort = 13002
|
||||
```
|
||||
|
||||
然后在 VPS Nginx 中添加对应的反代和域名即可。
|
||||
|
||||
---
|
||||
|
||||
## 经验教训
|
||||
|
||||
> [!warning] 坑1：FRP proxy type 选错
|
||||
> frpc 中 gitea-web 的 `type` 不能用 `http`，除非 frps 配置了 `vhostHTTPPort`。**直接用 `type = "tcp"` 最简单可靠。**
|
||||
|
||||
> [!warning] 坑2：多个 frpc 实例冲突
|
||||
> NAS 上可能同时跑了多个 frpc 进程，导致 proxy name 冲突（`proxy already exists`）。修改配置后确保**先停旧进程再启新进程**。
|
||||
|
||||
> [!warning] 坑3：remotePort 与 VPS 服务冲突
|
||||
> `remotePort = 3000` 会和常见服务冲突。建议穿透端口用 `13xxx` 或 `10xxx` 段。
|
||||
|
||||
> [!warning] 坑4：域名 DNS 服务器不在腾讯云
|
||||
> `haiguang.com` 的 DNS 指向加速乐，在腾讯云加的 A 记录不会生效。解决：换用 `haiguang.xyz`（DNS 在腾讯云）。
|
||||
|
||||
> [!warning] 坑5：Gitea ROOT_URL 未更新
|
||||
> Gitea 安装时 ROOT_URL 默认是内网地址（如 `http://192.168.123.21:8418/`），必须改为 `https://git.haiguang.xyz/`，否则页面链接、Webhook、OAuth 等功能全部异常。
|
||||
|
||||
> [!tip] 资源紧张时的优化建议
|
||||
> - VPS 内存仅 2GB，OpenClaw 占 47%，选择 SQLite 而非 MySQL/PostgreSQL 节省了约 200MB
|
||||
> - frps 仅占 9MB，几乎无感
|
||||
> - 如果后续需要更多服务穿透，建议升级 VPS 内存到 4GB
|
||||
|
||||
---
|
||||
|
||||
*部署时间：2026-03-28 ~ 2026-03-29*
|
||||
|
||||
*文档更新：2026-03-29*
|
||||
Reference in New Issue
Block a user