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:
@@ -0,0 +1,813 @@
|
||||
---
|
||||
categories:
|
||||
- "[[LLM Wiki]]"
|
||||
tags:
|
||||
- wiki
|
||||
- concept
|
||||
- gitea
|
||||
- deployment
|
||||
- frp
|
||||
- nas
|
||||
created: 2026-04-07
|
||||
source: "[[Gitea个人Git服务部署指南]]"
|
||||
type: concept
|
||||
aliases:
|
||||
- 自建Git服务
|
||||
- NAS代码仓库
|
||||
- FRP内网穿透
|
||||
---
|
||||
|
||||
# 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>
|
||||
Reference in New Issue
Block a user