# 网络拓扑文档

> 最后更新：2026-03-04

---

## 🗺️ 网络架构概览（当前生效）

```
                                ┌───────────────────────────┐
                                │         公网用户          │
                                └─────────────┬─────────────┘
                                              │
                                              ▼
                           ┌────────────────────────────────────┐
                           │ 香港入口服务器 103.118.245.6        │
                           │ - Nginx: 80/443                    │
                           │ - FRPS: 7001                       │
                           │ - FRP vhost: 8080/8443             │
                           │ - Dashboard: 7500                  │
                           └────────────────┬───────────────────┘
                                            │ FRP (token)
                                            ▼
                           ┌────────────────────────────────────┐
                           │ 生产服务器 192.168.58.20           │
                           │ - Next.js: 4320 (容器映射)         │
                           │ - MinIO: 9000                      │
                           │ - frpc-s3.service (主链路)         │
                           │ - frpc.service (南京备用，已停用)  │
                           └────────────────────────────────────┘

备用（非主链路）：
南京 FRP 180.97.221.140（7000/2320/2330）当前仅保留为历史备用线路。
```

---

## 🌐 域名解析

| 域名 | DNS 指向 | 实际服务 | 用途 |
|-----|---------|---------|------|
| 3d.yydd.ai | 香港 (103.118.245.6) | Next.js 应用（经香港入口转发） | 主站访问 |
| s3.yydd.ai | 香港 (103.118.245.6) | MinIO 存储桶（经香港入口转发） | 文件存储/下载 |

### DNS 管理说明

- DNS 托管在 Cloudflare（权威 NS：`holly.ns.cloudflare.com`、`simon.ns.cloudflare.com`）
- 域名变更需在 Cloudflare Zone（`yydd.ai`）内操作
- 当前运维终端默认无 Cloudflare 管理权限时，需联系域名管理员执行切换

---

## 🔌 FRP 穿透配置

### 当前服务模型（systemd）

| 节点 | 服务 | 配置文件 | 角色 |
|-----|------|---------|------|
| 生产 192.168.58.20 | `frpc-s3.service` | `/etc/frp/frpc-s3.toml` | 主链路（3d + s3 → 香港） |
| 生产 192.168.58.20 | `frpc.service` | `/etc/frp/frpc.toml` | 南京备用链路（当前停用） |
| 香港 103.118.245.6 | `frps-minio.service` | `/root/frp-minio/frps.toml` | FRPS 服务端 |

> 说明：`frpc` 二进制会有工作线程，进程数可大于 1；以 `systemctl is-active` 与日志为准。
>
> 运行备注：`frpc.service`（南京备用链路）当前已停用，不影响 `frpc-s3.service`（香港主链路）对外服务；如需回切可手动启用。

### 关键配置（脱敏示例）

#### `/etc/frp/frpc-s3.toml`（生产，主链路）

```toml
serverAddr = "103.118.245.6"
serverPort = 7001

auth.method = "token"
auth.token = "<REDACTED>"

[[proxies]]
name = "minio-s3-hk"
type = "http"
localIP = "192.168.58.20"
localPort = 9000
customDomains = ["s3.yydd.ai"]

[[proxies]]
name = "3d-main-hk"
type = "http"
localIP = "192.168.58.20"
localPort = 4320
customDomains = ["3d.yydd.ai"]
```

#### `/root/frp-minio/frps.toml`（香港，服务端）

```toml
bindPort = 7001
vhostHTTPPort = 8080
vhostHTTPSPort = 8443

[auth]
token = "<REDACTED>"

[webServer]
addr = "0.0.0.0"
port = 7500
user = "admin"
password = "<REDACTED>"
```

---

## 🚪 端口映射（当前）

### 生产服务器 (192.168.58.20)

| 服务 | 端口 | 说明 |
|-----|------|------|
| Next.js 容器 | 4320 | 3D 主站应用入口（内网） |
| MinIO | 9000 | 对象存储服务 |
| PostgreSQL | 5432 | 内网数据库 |
| Redis | 6379 | 内网缓存 |

### 香港入口服务器 (103.118.245.6)

| 端口 | 服务 | 说明 |
|-----|------|------|
| 80 | Nginx | HTTP 入口（跳 HTTPS） |
| 443 | Nginx + Let’s Encrypt | 3d/s3 统一 HTTPS 入口 |
| 7001 | FRPS bindPort | FRP 控制通道 |
| 8080 | FRPS vhostHTTPPort | FRP HTTP 转发 |
| 8443 | FRPS vhostHTTPSPort | FRP HTTPS 转发 |
| 7500 | FRPS Dashboard | 运维面板（需加固来源） |

### 南京 FRP 服务器 (180.97.221.140)

| 端口 | 服务 | 说明 |
|-----|------|------|
| 7000 | FRP Server | 南京旧线路控制端口 |
| 2320 | 3d 旧代理口 | 历史主站链路（备用） |
| 2330 | s3 旧代理口 | 历史存储链路（备用） |

---

## 📊 服务访问路径（当前）

### 3d.yydd.ai（主站）

```
用户 → DNS(香港) → Nginx(香港:443) → FRPS(香港:8080/8443) → frpc-s3(生产) → Next.js(4320)
```

### s3.yydd.ai（存储）

```
用户 → DNS(香港) → Nginx(香港:443) → FRPS(香港:8080/8443) → frpc-s3(生产) → MinIO(9000)
```

---

## 🔧 故障排查（更新后）

### 常用检查命令

```bash
# 1) 生产侧 FRP 主链路
ssh root@192.168.58.20 "systemctl is-active frpc-s3 && tail -n 80 /tmp/frpc-s3.log"

# 2) 香港侧 FRPS + Nginx
ssh -i C:/Users/54972/.ssh/id_rsa_103.118.245.6 root@103.118.245.6 "systemctl is-active frps-minio nginx"
ssh -i C:/Users/54972/.ssh/id_rsa_103.118.245.6 root@103.118.245.6 "ss -tlnp | grep -E ':7001 |:8080 |:8443 |:443 '"

# 3) 端到端验证
curl -sS -o /dev/null -w "3d:%{http_code} ssl=%{ssl_verify_result}\n" https://3d.yydd.ai
curl -sS -o /dev/null -w "s3:%{http_code} ssl=%{ssl_verify_result}\n" https://s3.yydd.ai
```

### 常见问题

| 问题 | 可能原因 | 解决方案 |
|-----|---------|---------|
| 3d.yydd.ai 502/超时 | 香港 `frps-minio` 未运行或端口冲突 | `systemctl status frps-minio`，排查 `7500` 占用并重启 |
| s3.yydd.ai 不可用 | `frpc-s3` 未连接香港 | 检查 `/tmp/frpc-s3.log` 是否 `login success` + `start proxy success` |
| HTTPS 证书报错 | Nginx 证书未覆盖双域名 | 检查 `/etc/letsencrypt/live/s3.yydd.ai/fullchain.pem` SAN |
| 访问慢/抖动 | 跨境链路波动 | 观察 `frpc-s3` 重连频率，必要时启用备用线路 |

### 重启流程（systemd）

```bash
# 生产：重启香港主链路 frpc
ssh root@192.168.58.20 "systemctl restart frpc-s3 && systemctl status frpc-s3 --no-pager -l | sed -n '1,60p'"

# 生产：启用南京备用链路（仅回切时）
ssh root@192.168.58.20 "systemctl enable --now frpc && systemctl status frpc --no-pager -l | sed -n '1,60p'"

# 香港：重启 FRPS
ssh -i C:/Users/54972/.ssh/id_rsa_103.118.245.6 root@103.118.245.6 "systemctl restart frps-minio && systemctl status frps-minio --no-pager -l | sed -n '1,60p'"

# 香港：重载 Nginx（改证书/站点后）
ssh -i C:/Users/54972/.ssh/id_rsa_103.118.245.6 root@103.118.245.6 "nginx -t && systemctl reload nginx"
```

---

## 🔐 服务器凭据与连接方式

| 服务器 | IP | 推荐 SSH 方式 | 备注 |
|-------|-----|-------------|------|
| 生产服务器 | 192.168.58.20 | `ssh prod` | 主服务节点 |
| 香港入口 | 103.118.245.6 | `ssh -i C:/Users/54972/.ssh/id_rsa_103.118.245.6 root@103.118.245.6` | 已切换为新密钥 |
| 南京 FRP | 180.97.221.140 | `plink -ssh root@180.97.221.140 -pw "密码"` | 备用链路 |
| 构建服务器 | 192.168.42.134 | `ssh build` | 镜像构建 |

> 详细密钥清单与服务器说明见 `CLAUDE.md`。

---

## 📝 变更历史

| 日期 | 变更内容 | 操作人 |
|-----|---------|-------|
| 2026-02-23 | 创建文档，记录初始网络架构 | Claude |
| 2026-03-04 | 3d 主链路切到香港，证书覆盖 3d+s3，文档改为 systemd 运维模型 | Codex |