ishenwei/nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

合并文档并更新

Browse Source
This commit is contained in:
admin
2026-06-04 15:12:25 +08:00
parent b147c5730f
commit 836bbdd90d
3 changed files with 1291 additions and 980 deletions
Download Patch File Download Diff File Expand all files Collapse all files

546
knowledgebase/FRP 配置详细笔记.md Normal file
View File

@@ -0,0 +1,546 @@
---
title: FRP 配置详细笔记
source:
author: shenwei
published:
created: 2026-04-03
description:
tags: [frp, macos, ubuntu]
---
# FRP 配置详细笔记
#frp #macos #ubuntu
## 概述
本文档记录 macmini、ubuntu1、ubuntu2、NAS 四个服务器上的 FRP（Fast Reverse Proxy）客户端配置信息。
---
## 服务器配置总览
| 服务器 | FRP目录 | 配置文件 |
| ------- | ---------------------------------- | ----------- |
| macmini | `/opt/frp/frp_0.65.0_darwin_arm64` | `frpc.toml` |
| ubuntu1 | `/opt/frp/frp_0.65.0_linux_amd64` | `frpc.toml` |
| ubuntu2 | `/opt/frp/frp_0.65.0_linux_amd64` | `frpc.toml` |
| NAS | `/opt/frp/frp_0.65.0_linux_amd64` | `frpc.toml` |
| | | |
---
## FRP 服务器信息
| 配置项 | 值 |
|--------|-----|
| serverAddr | 192.227.222.142 (VPS1) |
| serverPort | 7000 |
| auth.token | Gg8sqHJVgh42KQ0oTatMjl6AywWqAzaaT0B77a4qD46tXtoH9j9mXb2k1YitObhs |
| webServer.addr | 127.0.0.1 |
| webServer.port | 7400 |
| webServer.user | admin |
| webServer.password | admin |
---
## 1. MacMini 配置
### 基本信息
- **FRP目录**: `/opt/frp/frp_0.65.0_darwin_arm64`
- **配置文件**: `frpc.toml`
- **运行用户**: root (通过 tmux 管理)
### 代理配置列表
| 名称 | 类型 | LocalPort | RemotePort | 说明 |
|------|------|------------|-------------|------|
| macmini-ssh | tcp | 22 | 60026 | SSH反向代理 |
| n8n | tcp | 5678 | 15679 | n8n自动化工具 |
| vaultwarden | tcp | 5151 | 15151 | 密码管理器 |
| it-tools | tcp | 8999 | 18999 | IT工具集合 |
| drawio | tcp | 8085 | 18085 | 绘图工具 |
### 完整配置文件内容
```toml
# frpc.toml
# 客户端配置文件
# 服务器地址与认证
serverAddr = "192.227.222.142"
serverPort = 7000
auth.method = "token"
auth.token = "Gg8sqHJVgh42KQ0oTatMjl6AywWqAzaaT0B77a4qD46tXtoH9j9mXb2k1YitObhs"
# 日志配置
log.level = "info"
log.maxDays = 3
log.disablePrintColor = false
# 管理界面（可选）
webServer.addr = "127.0.0.1"
webServer.port = 7400
webServer.user = "admin"
webServer.password = "admin"
# 代理配置
[[proxies]]
name = "macmini-ssh"
type = "tcp"
localIP = "127.0.0.1"
localPort = 22
remotePort = 60026
[[proxies]]
name = "n8n"
type = "tcp"
localIP = "127.0.0.1"
localPort = 5678
remotePort = 15679
[[proxies]]
name = "vaultwarden"
type = "tcp"
localIP = "127.0.0.1"
localPort = 5151
remotePort = 15151
[[proxies]]
name = "it-tools"
type = "tcp"
localIP = "127.0.0.1"
localPort = 8999
remotePort = 18999
[[proxies]]
name = "drawio"
type = "tcp"
localIP = "127.0.0.1"
localPort = 8085
remotePort = 18085
```
## 2. Ubuntu1 配置
### 基本信息
- **FRP目录**: `/opt/frp/frp_0.65.0_linux_amd64`
- **配置文件**: `frpc.toml`
- **运行用户**: root (通过 systemd 管理)
### 代理配置列表
| 名称 | 类型 | LocalPort | RemotePort | 说明 |
|------|------|------------|-------------|------|
| ubuntu1-ssh | tcp | 22 | 60022 | SSH反向代理 |
| transmission | tcp | 9091 | 19091 | BT下载 |
| grafana | tcp | 3000 | 13000 | 监控面板 |
| homarr | tcp | 7575 | 17575 | 导航面板 |
| superset | tcp | 8777 | 18777 | 数据可视化 |
| tk | tcp | 8888 | 18888 | TikTok生产环境 |
| portainer | tcp | 9000 | 19443 | Docker管理 |
| stq | tcp | 5173 | 15173 | STQ开发 |
| stq-admin | tcp | 7000 | 17000 | STQ管理后台 |
| stq-n8n | tcp | 62000 | 15678 | STQ n8n |
### 完整配置文件内容
```toml
# frpc.toml
# 客户端配置文件
# 服务器地址与认证
serverAddr = "192.227.222.142"
serverPort = 7000
auth.method = "token"
auth.token = "Gg8sqHJVgh42KQ0oTatMjl6AywWqAzaaT0B77a4qD46tXtoH9j9mXb2k1YitObhs"
# 日志配置
log.level = "info"
log.maxDays = 3
log.disablePrintColor = false
# 管理界面（可选）
webServer.addr = "127.0.0.1"
webServer.port = 7400
webServer.user = "admin"
webServer.password = "admin"
[[proxies]]
name = "transmission"
type = "tcp"
localIP = "127.0.0.1"
localPort = 9091
remotePort = 19091
[[proxies]]
name = "grafana"
type = "tcp"
localIP = "127.0.0.1"
localPort = 3000
remotePort = 13000
[[proxies]]
name = "ubuntu1-ssh"
type = "tcp"
localIP = "127.0.0.1"
localPort = 22
remotePort = 60022
[[proxies]]
name = "homarr"
type = "tcp"
localIP = "127.0.0.1"
localPort = 7575
remotePort = 17575
[[proxies]]
name = "superset"
type = "tcp"
localIP = "127.0.0.1"
localPort = 8777
remotePort = 18777
[[proxies]]
name = "tk"
type = "tcp"
localIP = "127.0.0.1"
localPort = 8888
remotePort = 18888
[[proxies]]
name = "ubuntu1-portainer"
type = "tcp"
localIP = "127.0.0.1"
localPort = 9000
remotePort = 19443
[[proxies]]
name = "stq"
type = "tcp"
localIP = "127.0.0.1"
localPort = 5173
remotePort = 15173
[[proxies]]
name = "stq-admin"
type = "tcp"
localIP = "127.0.0.1"
localPort = 7000
remotePort = 17000
[[proxies]]
name = "stq-n8n"
type = "tcp"
localIP = "127.0.0.1"
localPort = 62000
remotePort = 15678
```
---
## 3. Ubuntu2 配置
### 基本信息
- **FRP目录**: `/opt/frp/frp_0.65.0_linux_amd64`
- **配置文件**: `frpc.toml`
- **运行用户**: root (通过 systemd 管理)
### 代理配置列表
| 名称 | 类型 | LocalPort | RemotePort | 说明 |
|------|------|------------|-------------|------|
| ubuntu2-ssh | tcp | 22 | 60024 | SSH反向代理 |
| tk-dev | tcp | 8888 | 18889 | TikTok开发环境 |
### 完整配置文件内容
```toml
# frpc.toml
# 客户端配置文件
# 服务器地址与认证
serverAddr = "192.227.222.142"
serverPort = 7000
auth.method = "token"
auth.token = "Gg8sqHJVgh42KQ0oTatMjl6AywWqAzaaT0B77a4qD46tXtoH9j9mXb2k1YitObhs"
# 日志配置
log.level = "info"
log.maxDays = 3
log.disablePrintColor = false
# 管理界面（可选）
webServer.addr = "127.0.0.1"
webServer.port = 7400
webServer.user = "admin"
webServer.password = "admin"
# 示例1：SSH 反向代理（将本地 22 端口暴露到服务器的 60024 端口）
[[proxies]]
name = "ubuntu2-ssh"
type = "tcp"
localIP = "127.0.0.1"
localPort = 22
remotePort = 60024
[[proxies]]
name = "tk-dev"
type = "tcp"
localIP = "127.0.0.1"
localPort = 8888
remotePort = 18889
```
---
## 4. NAS 配置
### 基本信息
- **FRP目录**: `/opt/frp/frp_0.65.0_linux_amd64`
- **配置文件**: `frpc.toml`
- **运行用户**: root (通过 systemd 管理)
### 代理配置列表
| 名称 | 类型 | LocalPort | RemotePort | 说明 |
|------|------|------------|-------------|------|
| nas | tcp | 5000 | 15000 | DSM管理界面 |
| navidrome | tcp | 4533 | 14533 | 音乐服务器 |
| calibre | tcp | 8083 | 18083 | 电子书管理 |
| webdav | tcp | 5005 | 65005 | WebDAV服务 |
| miniflux | tcp | 8080 | 18080 | RSS阅读器 |
| zipline | tcp | 3333 | 13333 | URL短链接 |
| nas_ssh | tcp | 22 | 60023 | SSH反向代理 |
| mysql | tcp | 3307 | 63307 | MySQL数据库 |
| nas_web | tcp | 80 | 10080 | Web服务 |
| jellyfin | tcp | 8096 | 18096 | 媒体服务器 |
### 完整配置文件内容
```toml
# FRP Client Configuration for NAS
# Converted from frpc.ini
serverAddr = "192.227.222.142"
serverPort = 7000
[auth]
token = "Gg8sqHJVgh42KQ0oTatMjl6AywWqAzaaT0B77a4qD46tXtoH9j9mXb2k1YitObhs"
[[proxies]]
name = "nas"
type = "tcp"
localIP = "127.0.0.1"
localPort = 5000
remotePort = 15000
[[proxies]]
name = "navidrome"
type = "tcp"
localIP = "127.0.0.1"
localPort = 4533
remotePort = 14533
[[proxies]]
name = "calibre"
type = "tcp"
localIP = "127.0.0.1"
localPort = 8083
remotePort = 18083
[[proxies]]
name = "webdav"
type = "tcp"
localIP = "127.0.0.1"
localPort = 5005
remotePort = 65005
[[proxies]]
name = "miniflux"
type = "tcp"
localIP = "127.0.0.1"
localPort = 8080
remotePort = 18080
[[proxies]]
name = "zipline"
type = "tcp"
localIP = "127.0.0.1"
localPort = 3333
remotePort = 13333
[[proxies]]
name = "nas_ssh"
type = "tcp"
localIP = "127.0.0.1"
localPort = 22
remotePort = 60023
[[proxies]]
name = "mysql"
type = "tcp"
localIP = "127.0.0.1"
localPort = 3307
remotePort = 63307
[[proxies]]
name = "nas_web"
type = "tcp"
localIP = "127.0.0.1"
localPort = 80
remotePort = 10080
[[proxies]]
name = "jellyfin"
type = "tcp"
localIP = "127.0.0.1"
localPort = 8096
remotePort = 18096
```
---
## 端口映射汇总
### 按 RemotePort 排序
| RemotePort | 服务器 | 服务名称 |
| ---------- | ------- | ------------ |
| 60022 | ubuntu1 | ubuntu1-ssh |
| 60023 | NAS | nas_ssh |
| 60024 | ubuntu2 | ubuntu2-ssh |
| 60026 | macmini | macmini-ssh |
| 10080 | NAS | nas_web |
| 13000 | ubuntu1 | grafana |
| 13333 | NAS | zipline |
| 14533 | NAS | navidrome |
| 15000 | NAS | nas |
| 15151 | macmini | vaultwarden |
| 15173 | ubuntu1 | stq |
| 15678 | ubuntu1 | stq-n8n |
| 15679 | macmini | n8n |
| 17000 | ubuntu1 | stq-admin |
| 17575 | ubuntu1 | homarr |
| 18083 | NAS | calibre |
| 18085 | macmini | drawio |
| 18096 | NAS | jellyfin |
| 18777 | ubuntu1 | superset |
| 18888 | ubuntu1 | tk |
| 18889 | ubuntu2 | tk-dev |
| 18999 | macmini | it-tools |
| 19091 | ubuntu1 | transmission |
| 19443 | ubuntu1 | portainer |
| 63307 | NAS | mysql |
| 65005 | NAS | webdav |
| 12222 | NAS | gitea-ssh |
| 13001 | NAS | gitea-web |
---
## FRP 管理命令
### MacMini
#### 查看状态
```bash
# SSH到服务器后连接tmux会话
ssh <服务器名>
tmux attach -t frpc
```
#### 重启FRP
```bash
# 在tmux中按 Ctrl+C 停止，然后重新运行
./frpc -c frpc.toml
```
### Ubuntu1/Ubuntu2/NAS
#### 查看状态
```bash
ssh <服务器名>
systemctl status frpc
```
#### 重启FRP
```bash
systemctl restart frpc
```
#### 配置FRP service
```bash
# Reload systemd manager configuration
systemctl daemon-reload
# Stop Service
systemctl stop frpc
# Start Service
systemctl start frpc
# Check service status
systemctl status frpc
```
#### 配置frpc.service
```
cd /etc/systemd/system
# ubuntu1/ubuntu2
nano frpc.service
# nas
vi frpc.service
```
```python
[Unit]
Description=frp client
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
ExecStart=/opt/frp/frp_0.65.0_linux_amd64/frpc -c /opt/frp/frp_0.65.0_linux_amd64/frpc.toml
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
```
### 常用命令速查
| 服务器 | SSH别名 | FRP目录 | 启动命令 |
| ------- | ------------- | -------------------------------- | ---- |
| macmini | `ssh macmini` | /opt/frp/frp_0.65.0_darwin_arm64 | frpc |
| ubuntu1 | `ssh ubuntu1` | /opt/frp/frp_0.65.0_linux_amd64 | frpc |
| ubuntu2 | `ssh ubuntu2` | /opt/frp/frp_0.65.0_linux_amd64 | frpc |
| NAS | `ssh nas` | /opt/frp/frp_0.65.0_linux_amd64 | frpc |
---
## 相关域名映射
| 域名 | 服务器 | 目标服务 | RemotePort |
| ---------------------------- | ------- | ------------ | ---------- |
| n8n.ishenwei.online | macmini | n8n | 15679 |
| vaultwarden.ishenwei.online | NAS | vaultwarden | 15151 |
| it-tools.ishenwei.online | macmini | it-tools | 18999 |
| drawio.ishenwei.online | macmini | drawio | 18085 |
| tk.ishenwei.online | ubuntu1 | tk | 18888 |
| tk-dev.ishenwei.online | ubuntu2 | tk-dev | 18889 |
| grafana.ishenwei.online | ubuntu1 | grafana | 13000 |
| superset.ishenwei.online | ubuntu1 | superset | 18777 |
| dashboard.ishenwei.online | ubuntu1 | homarr | 17575 |
| transmission.ishenwei.online | ubuntu1 | transmission | 19091 |
| nas.ishenwei.online | NAS | DSM | 15000 |
| navidrome.ishenwei.online | NAS | navidrome | 14533 |
| calibre.ishenwei.online | NAS | calibre-web | 18083 |
| jellyfin.ishenwei.online | NAS | jellyfin | 18096 |
| zipline.ishenwei.online | NAS | zipline | 13333 |
| gitea.ishenwei.online | NAS | gitea | 13001 |

745
knowledgebase/Gitea 完整配置指南（SSH + frp + Caddy）.md Normal file
View File

@@ -0,0 +1,745 @@
---
title: Gitea 完整配置指南（SSH + frp + Caddy）
author: shenwei
created: 2026-06-04
description: 涵盖 Gitea SSH 配置、frp 转发、Caddy 反代、以及客户端配置的完整指南
tags: [git, gitea, ssh, frp, caddy, docker]
---
# Gitea 完整配置指南（SSH + frp + Caddy）
这是一份综合指南，涵盖 Gitea 的完整配置，包括 SSH 设置、通过 frp 和 Caddy 进行远程访问、以及 Git 客户端配置。
## 目录
1. [第一部分：Gitea 部署与基础 SSH 配置](#第一部分gitea-部署与基础-ssh-配置)
2. [第二部分：远程访问架构（frp + Caddy）](#第二部分远程访问架构frp--caddy)
3. [第三部分：客户端配置](#第三部分客户端配置)
4. [第四部分：故障排除](#第四部分故障排除)
5. [第五部分：最佳实践](#第五部分最佳实践)
---
# 第一部分：Gitea 部署与基础 SSH 配置
## 1. Docker 部署（推荐标准配置）
### 基础 Docker Compose 配置
```yaml
version: "3"
services:
gitea:
image: gitea/gitea:latest
container_name: gitea
restart: always
ports:
- "3000:3000" # Web UI HTTP
- "2222:22" # SSH（宿主机 2222 -> 容器内 22）
volumes:
- ./gitea:/data
environment:
- ROOT_URL=http://localhost:3000
```
**为什么用 2222？**
- 宿主机的 22 端口通常已被系统 SSH 占用
- 使用 `2222 → 22` 映射避免冲突
- 容器内 Gitea SSH 服务依然运行在 22，外部通过 2222 访问
---
## 2. Gitea SSH 服务启用
### 检查配置
进入容器检查配置：
```bash
docker exec -it gitea /bin/sh
cat /data/gitea/conf/app.ini
```
确保 `[server]` 部分包含：
```ini
[server]
START_SSH_SERVER = true
SSH_PORT = 22
```
- `START_SSH_SERVER = true`：启用 SSH 服务
- `SSH_PORT = 22`：容器内监听 22 端口（通过 Docker 映射到外部端口）
### 重启服务
```bash
docker compose down
docker compose up -d
```
---
## 3. 基础 SSH 连接测试
### 测试 SSH 连通性（本地网络）
```bash
# 使用指定端口连接
ssh -T git@192.168.3.17 -p 2222
```
**预期输出（成功）：**
```
Hi username! You've successfully authenticated with the key named ...
Gitea does not provide shell access.
```
### 常见错误与修复
#### ❌ Connection refused
```
ssh: connect to host ... port 2222: Connection refused
```
**原因：** Docker 未正确映射端口
**修复：** 检查 docker-compose.yml 中是否有 `- "2222:22"`
#### ❌ Connection closed
```
Connection closed by 192.168.3.17 port 2222
```
**原因：** SSH 服务存在但不是 Gitea 在处理，或 Gitea SSH 未启用
**修复：**
1. 检查 `app.ini` 中 `START_SSH_SERVER = true`
2. 重启 Docker 容器
#### ❌ Permission denied (publickey)
```
Permission denied (publickey)
```
**原因：** SSH key 未在 Gitea 中添加或未加载
**修复：**
```bash
# 确保公钥已添加到 Gitea
# 在 Gitea Web UI → Settings → SSH Keys 中验证
# 或重新加载 SSH Agent
ssh-add ~/.ssh/id_ed25519
```
---
# 第二部分：远程访问架构（frp + Caddy）
## 1. 整体架构
### 正确的访问方式
```
┌─────────────────────────────────────────────────────────┐
│ 远程访问架构 │
├─────────────────────────────────────────────────────────┤
│ │
│ HTTP 访问（通过 Caddy 反代） │
│ 浏览器 → Caddy :443 → frps :13000 → Gitea :3000 │
│ │
│ SSH 访问（直接转发，绕过 Caddy） │
│ Git Client → frps :12222 → Gitea :2222 │
│ │
└─────────────────────────────────────────────────────────┘
```
### 核心原则
1. **HTTP 走 Caddy**：Web 浏览器通过 Caddy 反代访问 Gitea Web UI
2. **SSH 直接转发**：SSH 流量不经过 Caddy（Caddy 是 HTTP 代理，无法处理 SSH TCP 流量）
3. **防火墙放行**：frps 服务器必须在防火墙中放行相应端口
---
## 2. frpc 配置（本地端，如 NAS）
### frpc.toml 配置文件
```toml
serverAddr = "your-vps.com"
serverPort = 7000
auth.method = "token"
auth.token = "your-token"
# HTTP 转发 - 给 Caddy 用
[[proxies]]
name = "gitea-http"
type = "tcp"
localIP = "127.0.0.1"
localPort = 3000
remotePort = 13001
# SSH 转发 - 直接暴露
[[proxies]]
name = "gitea-ssh"
type = "tcp"
localIP = "127.0.0.1"
localPort = 2222
remotePort = 12222
```
**配置说明：**
- `remotePort = 13001`：Caddy 通过此端口访问 Gitea Web UI
- `remotePort = 12222`：Git 客户端通过此端口连接 SSH
---
## 3. frps 配置（服务器端，如 VPS）
### frps.toml 配置文件
```toml
bindAddr = "0.0.0.0"
bindPort = 7000
auth.method = "token"
auth.token = "your-token"
```
### 防火墙配置
**在 VPS 上放行端口：**
```bash
# UFW（Ubuntu/Debian）
ufw allow 7000/tcp # frp 通信
ufw allow 13001/tcp # Gitea Web（给 Caddy）
ufw allow 12222/tcp # Gitea SSH
# iptables
iptables -A INPUT -p tcp --dport 7000 -j ACCEPT
iptables -A INPUT -p tcp --dport 13001 -j ACCEPT
iptables -A INPUT -p tcp --dport 12222 -j ACCEPT
```
**AWS/阿里云/腾讯云等云服务：**
- 需要同时配置安全组（云控制台）和系统防火墙
- 缺一不可
---
## 4. Caddy 反代配置
### Caddyfile 配置
```caddy
gitea.yourdomain.com {
reverse_proxy 127.0.0.1:13001
}
```
**关键点：**
- 反代目标是 `127.0.0.1:13001`（frps 转发来的 HTTP 流量）
- **不要将 SSH 端口（12222）配进 Caddy**
- Caddy 只负责 HTTP/HTTPS，不处理 SSH
---
## 5. Gitea app.ini 配置
### SSH 相关配置
编辑 `/data/gitea/conf/app.ini`：
```ini
[server]
ROOT_URL = https://gitea.ishenwei.online/
SSH_DOMAIN = gitea.ishenwei.online
SSH_PORT = 12222
START_SSH_SERVER = true
```
**配置说明：**
- `SSH_DOMAIN = gitea.ishenwei.online`：Web 界面显示的 SSH 地址
- `SSH_PORT = 12222`：对外暴露的 SSH 端口（影响 Web 上显示的 Clone 地址）
- `ROOT_URL`：Web UI 根路径，通常指向域名
### 重启应用
```bash
docker compose down
docker compose up -d
```
---
# 第三部分：客户端配置
## 1. SSH Key 生成
### 生成密钥对
```bash
ssh-keygen -t ed25519 -C "your-email@example.com"
```
**为什么用 ed25519？**
- 更安全、密钥更短
- 现代标准推荐
**默认路径：**
```
~/.ssh/id_ed25519 # 私钥
~/.ssh/id_ed25519.pub # 公钥
```
### 启动 SSH Agent
```bash
# Linux/macOS
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
# Windows (PowerShell)
# 通常自动运行，无需手动启动
ssh-add $env:USERPROFILE\.ssh\id_ed25519
```
---
## 2. 添加公钥到 Gitea
### 在 Gitea Web UI 中添加
1. 登录 Gitea Web UI
2. 点击右上角头像 → Settings
3. 选择 SSH Keys
4. 点击 Add Key
### 复制公钥内容
```bash
cat ~/.ssh/id_ed25519.pub
```
将输出内容完整复制到 Gitea，包括前缀 `ssh-ed25519 AAA...`
---
## 3. SSH Config 配置（推荐）
### 简化 SSH 连接
编辑 `~/.ssh/config`：
```bash
# 本地网络 - Gitea（Docker）
Host gitea-local
HostName 192.168.3.17
User git
Port 2222
IdentityFile ~/.ssh/id_ed25519
# 远程 - Gitea（通过 frp）
Host gitea.ishenwei.online
HostName gitea.ishenwei.online
User git
Port 12222
IdentityFile ~/.ssh/id_ed25519
```
### 使用简化命令
配置后，可以用更简洁的命令：
```bash
# 本地网络
ssh -T gitea-local
# 远程（通过 frp）
ssh -T gitea.yourdomain.com
```
---
## 4. Git 仓库配置
### 方式一：Clone 时使用 SSH
```bash
# 本地
git clone ssh://git@192.168.3.17:2222/username/repo.git
# 远程（通过 frp）
git clone ssh://git@gitea.ishenwei.online:12222/username/repo.git
# 使用 SSH Config 别名
git clone ssh://gitea-local/username/repo.git
git clone ssh://gitea.ishenwei.online/username/repo.git
```
### 方式二：修改已有仓库的 Remote URL
```bash
# 查看当前 remote
git remote -v
# 修改为 SSH
git remote set-url origin ssh://git@192.168.3.17:2222/username/repo.git
# 远程版本
git remote set-url origin ssh://git@gitea.ishenwei.online:12222/username/repo.git
# 验证修改
git remote -v
```
### 验证连接
```bash
git pull
```
---
## 5. VS Code / IDE 集成
在配置好 SSH 和 Git Remote 后：
- **VS Code**：无需额外配置，自动使用 Git + SSH
- **JetBrains IDE**：自动识别 SSH Config
- **其他 IDE**：通常也会自动识别系统 SSH 配置
**优势：**
- 无需输入密码
- 不受代理干扰
- Clone / Pull 不会卡住
---
# 第四部分：故障排除
## 1. SSH 连接测试
### 测试不同场景
```bash
# 本地网络测试
ssh -vT git@192.168.3.17 -p 2222
# 远程（通过 frp）测试
ssh -vT git@gitea.ishenwei.online -p 12222
# 使用 SSH Config 别名测试
ssh -vT gitea-local
ssh -vT gitea.ishenwei.online
```
### 详细调试信息
```bash
# -v 显示调试信息
# -vv 显示更详细信息
# -vvv 显示最详细信息
ssh -vvv git@gitea.ishenwei.online -p 12222
```
---
## 2. 常见问题
### 问题：Permission denied (publickey)
**可能原因：**
1. SSH key 未加载
2. 公钥未在 Gitea 中添加
3. 使用了错误的用户名（应该是 `git`，不是账户名）
**检修步骤：**
```bash
# 1. 查看已加载的 key
ssh-add -l
# 2. 如果列表为空，重新加载
ssh-add ~/.ssh/id_ed25519
# 3. 验证 Gitea Web UI 中是否已添加该公钥
# 4. 确认使用 git 用户
ssh -vT git@gitea.ishenwei.online -p 12222
```
### 问题：Connection refused
**可能原因：**
1. Gitea 未运行
2. SSH 端口未正确映射
3. 防火墙未放行端口
**检修步骤：**
```bash
# 1. 检查 Docker 容器状态
docker ps | grep gitea
# 2. 检查端口映射
docker port gitea
# 3. 检查防火墙（本地）
ss -tlnp | grep 2222
# 4. 检查防火墙（远程 VPS）
ufw status
```
### 问题：Connection closed by remote
**可能原因：**
1. SSH 服务异常关闭
2. 连接超时
3. 网络问题
**检修步骤：**
```bash
# 1. 重启 Gitea 容器
docker restart gitea
# 2. 检查容器日志
docker logs -f gitea
# 3. 测试基本连通性
ping gitea.ishenwei.online
```
### 问题：Bad owner or permissions on ~/.ssh/config
**原因：** SSH config 文件权限不正确
**修复：**
```bash
chmod 600 ~/.ssh/config
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub
```
---
## 3. 防火墙排查
### 本地网络（NAS/局域网）
```bash
# Windows - 测试端口连通性
Test-NetConnection -ComputerName 192.168.3.17 -Port 2222
# macOS/Linux - 测试端口连通性
nc -zv 192.168.3.17 2222
# 或使用 telnet
telnet 192.168.3.17 2222
```
### 远程 VPS
```bash
# 测试 frp 通信端口
telnet your-vps.com 7000
# 测试 Gitea HTTP 端口（给 Caddy）
telnet your-vps.com 13000
# 测试 Gitea SSH 端口
telnet your-vps.com 12222
```
### 群晖 NAS 防火墙
NAS 无 UFW，防火墙配置在：
- DSM → 控制面板 → 安全性 → 防火墙
- 需手动添加规则放行 frp 和 SSH 端口
---
## 4. frp 故障排除
### 检查 frp 日志
```bash
# 查看 frpc 日志
journalctl -u frpc -f
# 或直接运行 frpc 查看输出
./frpc -c frpc.toml
```
### 验证 frps 连接
```bash
# 在 VPS 上检查已连接的隧道
netstat -tlnp | grep 13000
netstat -tlnp | grep 12222
# 或使用 frp 的状态查询（如果启用了 admin 功能）
curl http://localhost:7400/api/serverinfo
```
---
# 第五部分：最佳实践
## 1. 安全建议
### SSH Key 管理
- ✅ 使用 ed25519 算法
- ✅ 为私钥设置强密码
- ✅ 定期轮换密钥
- ✅ 不同用途使用不同密钥（添加 `-C "标签"` 区分）
### 防火墙配置
- ✅ 只放行必要的端口
- ✅ 使用 VPN 或跳板机访问敏感服务
- ✅ 监控 SSH 连接日志
- ✅ 禁用密码认证，仅允许密钥认证
### Gitea 配置
- ✅ 设置强密码
- ✅ 启用 2FA（双因素认证）
- ✅ 定期备份仓库
- ✅ 监控访问日志
---
## 2. 性能优化
### SSH 连接复用
编辑 `~/.ssh/config` 添加连接复用：
```bash
Host *
ControlMaster auto
ControlPath ~/.ssh/control-%C
ControlPersist 600
ServerAliveInterval 60
ServerAliveCountMax 3
```
### Git 相关优化
```bash
# 配置 SSH 超时
git config --global core.sshCommand "ssh -o ConnectTimeout=10"
# 配置代理（如需要）
git config --global https.proxy [proxy-url]
```
---
## 3. 多环境管理
### SSH Config 示例
```bash
# 本地 Gitea
Host gitea-local
HostName 192.168.3.17
User git
Port 2222
IdentityFile ~/.ssh/id_ed25519_gitea
# 远程 Gitea（通过 frp）
Host gitea-remote
HostName gitea.ishenwei.online
User git
Port 12222
IdentityFile ~/.ssh/id_ed25519_gitea
# GitHub
Host github.com
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519_github
# GitLab
Host gitlab.com
HostName gitlab.com
User git
IdentityFile ~/.ssh/id_ed25519_gitlab
```
### Git 配置管理
```bash
# 查看当前配置
git config --list
# 全局配置
git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"
# 项目级配置（在仓库目录中）
git config --local user.email "project-specific@example.com"
```
---
## 4. 监控与维护
### 定期检查
```bash
# 检查 SSH key 过期情况
ssh-keygen -l -f ~/.ssh/id_ed25519.pub
# 查看 Gitea 日志
docker logs -f gitea
# 查看 frp 连接状态
journalctl -u frpc -f
```
### 日志轮转
确保日志不会占满磁盘：
```bash
# Docker 日志轮转配置（docker-compose.yml）
services:
gitea:
logging:
driver: "json-file"
options:
max-size: "100m"
max-file: "3"
```
---
# 总结
## 快速检查清单
部署完成后，按以下顺序验证：
- [ ] Docker 容器运行 `docker ps | grep gitea`
- [ ] SSH 服务启用 `docker exec gitea cat /data/gitea/conf/app.ini | grep SSH`
- [ ] 本地 SSH 连接 `ssh -T git@192.168.3.17 -p 2222`
- [ ] frp 连接正常 `journalctl -u frpc -f`
- [ ] SSH 端口放行（防火墙）`netstat -tlnp | grep 12222`
- [ ] Web UI 访问 浏览器打开 `https://gitea.yourdomain.com`
- [ ] 公钥已添加 Gitea Web UI 验证
- [ ] Git Clone 测试 `git clone ssh://git@gitea.yourdomain.com:12222/username/repo.git`
---
## 一句话结论
**Git 的本质：**
- `user.name` / `email` → 标识身份
- SSH Key → 认证身份
**推荐方案：**
> Gitea + Docker + SSH + frp + Caddy = 稳定可靠的远程 Git 服务
---
**记录时间：** 2026-06-04
**最后更新：** 2026-06-04