docs: add Tailscale MySQL middleware guide

cai

2026-07-02 758dafeab0836ad6a8959bb3fefcdcaeb69a67d8

docs: add Tailscale MySQL middleware guide

 middleware/Tailscale-MySQL-统一落地手册.md

New file
@@ -0,0 +1,570 @@
# Tailscale + 本地 MySQL 统一落地手册

## 1. 目标

把本地 Windows 上的 MySQL 通过 Tailscale 提供给你自己的其他主机和同事主机使用，并保留一台云主机作为链路兜底。

这份文档收敛以下三类内容：

1. 本地数据库机安装与放通
2. 云主机 Tailscale relay 部署
3. 远端主机接入、验证、连库和排障

## 2. 当前已落地环境

截至 `2026-07-02`，当前实际跑通的信息如下：

- 本地数据库机主机名：`DESKTOP-9KO3IVK`
- 本地数据库机 Tailscale IP：`100.100.67.109`
- 本地数据库机 MySQL 监听：`0.0.0.0:3306`
- 云主机节点名：`ts-relay-01`
- 云主机 Tailscale IP：`100.99.117.43`
- 云主机公网 IP：`124.221.105.128`
- MagicDNS 后缀：`tail6e2c27.ts.net`

当前已经确认过：

1. `DESKTOP-9KO3IVK` 在线
2. `ts-relay-01` 在线
3. 本地 MySQL 正在监听 `3306`
4. `root@'%'` 已存在，可用于你自己 tailnet 内部的临时管理连接

## 3. 链路拓扑

```text
远端主机
   |
   | 优先直连
   v
本地数据库机
(Windows + MySQL + Tailscale)
   ^
   | 直连失败时走 peer relay
   |
云主机
(CentOS 7 + Tailscale relay)
```

说明：

1. 优先走直连
2. 直连失败时优先走你自己的云主机 relay
3. relay 也不可用时，Tailscale 会退回 DERP
4. 这套方案解决的是可达性和稳定性，不会突破本地上行带宽上限

## 4. 方案选择

### 4.1 你自己的另一台主机

推荐做法：

1. 直接加入同一个 tailnet
2. 如果想让另一台机器上的 Codex 自动完成接入，使用 `auth key`
3. 如果没有 `auth key`，就执行 `tailscale up`，再人工点一次网页授权

适用场景：

- 这台机器属于你自己
- 你接受它算作你自己账号下的设备

### 4.2 同事的 Windows 主机

推荐做法：

1. 在 Tailscale 后台邀请同事加入同一个 tailnet
2. 同事用自己的 Tailscale 账号登录
3. 同事机器上的 Codex 完成安装和命令执行
4. 同事本人通常只需要做一次网页授权确认

不推荐直接用你的 `auth key` 把同事机器接入，除非你明确接受：

1. 这台设备算你统一代管
2. 设备身份默认偏向生成 key 的用户或 tag

## 5. 先决条件

开始前先确认：

1. 你有可登录的 Tailscale 账号
2. 本地数据库机可安装 Tailscale
3. 云主机安全组可放行 `UDP 40000`
4. 远端机器也能安装 Tailscale
5. 客户端尽量使用 `1.86+`

## 6. Tailscale 后台准备

### 6.1 用户组织

建议：

1. 你自己保留管理员账号
2. 同事各自使用自己的 Tailscale 账号
3. 不要多人共用一个 Tailscale 账号

### 6.2 Access controls

在 Tailscale 后台 `Access controls` 中合并类似配置：

```json
{
  "groups": {
    "group:db-users": [
      "你的Tailscale登录邮箱",
      "同事1邮箱",
      "同事2邮箱",
      "同事3邮箱"
    ]
  },
  "tagOwners": {
    "tag:relay": ["你的Tailscale登录邮箱"]
  },
  "acls": [
    {
      "action": "accept",
      "src": ["group:db-users"],
      "dst": ["100.100.67.109:3306"]
    }
  ]
}
```

说明：

1. `group:db-users` 是可访问数据库的用户组
2. `tag:relay` 用于云主机 relay
3. 这里的数据库目标地址已经写成当前真实地址 `100.100.67.109`

### 6.3 auth key 使用原则

建议：

1. 给你自己的新增主机使用 `one-off` 或可复用 `auth key`
2. 给云主机使用单独的 `auth key`
3. 不把旧的、可能已消费的 `one-off key` 当成长期文档常量

## 7. 本地数据库机配置

以下步骤适用于 `DESKTOP-9KO3IVK`。

### 7.1 安装并登录 Tailscale

下载安装：

- Windows：<https://tailscale.com/download/windows>

安装后登录当前 tailnet。

### 7.2 查看本机 Tailscale IP

```powershell
& "C:\Program Files\Tailscale\tailscale.exe" ip -4
```

当前实际值：

```text
100.100.67.109
```

### 7.3 检查 Tailscale 状态

```powershell
& "C:\Program Files\Tailscale\tailscale.exe" status
```

### 7.4 检查 MySQL 监听

```powershell
Get-CimInstance Win32_Service | Where-Object { $_.Name -eq "MySQL" } | Format-List Name,State,PathName
Get-NetTCPConnection -LocalPort 3306 -State Listen | Format-Table -AutoSize
```

当前预期：

1. 服务为 `Running`
2. `3306` 正在监听
3. 当前监听为 `0.0.0.0:3306`

### 7.5 放行 Windows 防火墙

建议仅放行 Tailscale 网段：

```powershell
New-NetFirewallRule -DisplayName "MySQL 3306 from Tailscale" `
  -Direction Inbound -Action Allow -Protocol TCP `
  -LocalPort 3306 -RemoteAddress 100.64.0.0/10
```

检查历史规则：

```powershell
Get-NetFirewallRule | Where-Object { $_.DisplayName -match "3306|MySQL" }
```

### 7.6 MySQL 账号策略

当前事实：

1. `root@'%'` 已放开
2. 适合你自己 tailnet 内部临时管理

长期建议：

1. 不长期用 `root` 做业务连接
2. 为同事或迁移工具单独建账号
3. 按用途分权限，默认先给只读

示例：

```sql
CREATE USER 'ts_trading_u1'@'100.101.102.103' IDENTIFIED BY '请替换成强密码1';
GRANT SELECT ON trading_xuntou.* TO 'ts_trading_u1'@'100.101.102.103';
FLUSH PRIVILEGES;
```

## 8. 云主机 relay 配置

以下步骤适用于 `124.221.105.128`。

### 8.1 放行安全组

放行：

- 协议：`UDP`
- 端口：`40000`

### 8.2 安装 Tailscale

```bash
curl -fsSL https://tailscale.com/install.sh | sh
sudo systemctl enable --now tailscaled
tailscale version
systemctl status tailscaled --no-pager
```

### 8.3 加入 tailnet

```bash
sudo tailscale up \
  --auth-key='请替换成新的有效auth-key' \
  --hostname='ts-relay-01' \
  --advertise-tags=tag:relay \
  --ssh
```

### 8.4 开启 relay

```bash
sudo tailscale set --relay-server-port=40000
```

检查：

```bash
tailscale ip -4
tailscale status
ss -lunp | grep 40000
```

当前实际节点信息：

- 节点名：`ts-relay-01`
- Tailscale IP：`100.99.117.43`

## 9. 远端主机接入

## 9.1 你自己的 Windows 主机

### 安装

```powershell
winget install --id Tailscale.Tailscale --exact --accept-source-agreements --accept-package-agreements
```

验证：

```powershell
$ts = 'C:\Program Files\Tailscale\tailscale.exe'
& $ts version
Get-Service Tailscale | Format-List Name,Status,StartType
```

### 用 auth key 自动加入

```powershell
$ts = 'C:\Program Files\Tailscale\tailscale.exe'
& $ts up --auth-key='请替换成新的有效auth-key' --hostname='my-workstation'
```

### 没有 auth key 时

```powershell
$ts = 'C:\Program Files\Tailscale\tailscale.exe'
& $ts up --hostname='my-workstation'
```

然后打开输出的授权链接，用你自己的 Tailscale 账号确认。

### 接入后验证

```powershell
$ts = 'C:\Program Files\Tailscale\tailscale.exe'
& $ts status
& $ts ip -4
& $ts ping 100.100.67.109
& $ts ping 100.99.117.43
Test-NetConnection 100.100.67.109 -Port 3306
```

## 9.2 同事的 Windows 主机

### 你先做的事

1. 在 Tailscale 后台邀请同事加入 tailnet
2. 告诉同事只需要在网页上登录并点确认
3. 不建议用你的 `auth key` 直接把同事机器并进来

### 同事机器上的标准步骤

```powershell
$ts = 'C:\Program Files\Tailscale\tailscale.exe'
if (Test-Path $ts) {
  & $ts version
  & $ts status
} else {
  winget install --id Tailscale.Tailscale --exact --accept-source-agreements --accept-package-agreements
}
```

加入 tailnet：

```powershell
$ts = 'C:\Program Files\Tailscale\tailscale.exe'
& $ts up --hostname='coworker-win-01'
```

如果输出授权链接，就打开浏览器让同事完成一次网页登录。

### 接入后验证

```powershell
$ts = 'C:\Program Files\Tailscale\tailscale.exe'
& $ts status
& $ts ip -4
& $ts ping 100.100.67.109
& $ts ping 100.99.117.43
Test-NetConnection 100.100.67.109 -Port 3306
```

## 9.3 Linux 主机

```bash
curl -fsSL https://tailscale.com/install.sh | sh
sudo systemctl enable --now tailscaled
sudo tailscale up --auth-key='请替换成新的有效auth-key' --hostname='my-server-02'
tailscale status
tailscale ip -4
tailscale ping 100.100.67.109
tailscale ping 100.99.117.43
```

## 10. 数据库连接信息

当前可直接使用：

- Host：`100.100.67.109`
- Port：`3306`
- 节点名：`DESKTOP-9KO3IVK`

如果只是先验证管理连接：

- User：`root`
- Host 权限：`root@'%'`

建议：

1. 先用 `Test-NetConnection` 验证网络
2. 再用 MySQL 客户端登录
3. 长期使用时改为单独业务账号

## 11. 标准验证顺序

不要跳步骤。顺序固定：

1. `tailscale status`
2. `tailscale ping 100.100.67.109`
3. `tailscale ping 100.99.117.43`
4. `Test-NetConnection 100.100.67.109 -Port 3306`
5. 最后再测 MySQL 用户名和密码

Windows 验证命令：

```powershell
$ts = 'C:\Program Files\Tailscale\tailscale.exe'
& $ts status
& $ts ping 100.100.67.109
& $ts ping 100.99.117.43
Test-NetConnection 100.100.67.109 -Port 3306
```

Linux 验证命令：

```bash
tailscale status
tailscale ping 100.100.67.109
tailscale ping 100.99.117.43
nc -zv 100.100.67.109 3306
```

## 12. 标准排障顺序

### 12.1 `tailscale ping` 不通

先判定为网络层问题，不要先改 MySQL。

重点检查：

1. 远端机器的 Tailscale 服务是否正常
2. 数据库机是否在线
3. 云主机 relay 是否在线

### 12.2 `tailscale ping` 通，但 `3306` 不通

回到数据库机 `DESKTOP-9KO3IVK` 检查：

```powershell
Get-NetTCPConnection -LocalPort 3306 -State Listen
netstat -ano | findstr :3306
```

重点确认：

1. MySQL 是否监听 `0.0.0.0:3306`
2. Windows 防火墙是否允许 `3306/TCP`
3. 再之后才看 MySQL 授权

### 12.3 一直走 DERP，不走 relay

检查：

1. 云主机是否已执行 `sudo tailscale set --relay-server-port=40000`
2. 安全组是否放行 `UDP 40000`
3. 客户端是否已经升级到较新的版本

### 12.4 速度慢

这是预期内的边界：

1. 速度上限取决于本地数据库机的上行带宽
2. 大查询跨公网时延迟会明显放大
3. relay 解决的是连通性，不是带宽倍增

## 13. Windows 客户端服务异常的恢复步骤

这次已经实际验证过一个高频故障：

1. MagicDNS 正常
2. 节点看起来在线
3. 但 `tailscale ping` 超时
4. 连 `ts-relay-01` 也一起超时

这种情况优先怀疑客户端自己的 Tailscale 服务卡住。

### 13.1 先做服务重启

```powershell
Restart-Service Tailscale
```

然后立刻复测：

```powershell
$ts = 'C:\Program Files\Tailscale\tailscale.exe'
& $ts ping 100.100.67.109
& $ts ping 100.99.117.43
Test-NetConnection 100.100.67.109 -Port 3306
```

### 13.2 再做进程级重拉起

```powershell
taskkill /F /IM tailscale-ipn.exe
taskkill /F /IM tailscale.exe
Start-Process 'C:\Program Files\Tailscale\tailscale-ipn.exe'
```

然后再测：

```powershell
$ts = 'C:\Program Files\Tailscale\tailscale.exe'
& $ts status
& $ts ping 100.100.67.109
& $ts ping 100.99.117.43
Test-NetConnection 100.100.67.109 -Port 3306
```

## 14. 给 Codex 的最短提示词

### 14.1 给你自己另一台机器上的 Codex

```text
请把当前机器加入我现有的 Tailscale tailnet，并验证到本地 MySQL 的网络连通性。

现有节点：
- DESKTOP-9KO3IVK / 100.100.67.109
- ts-relay-01 / 100.99.117.43
- MagicDNS 后缀：tail6e2c27.ts.net

要求：
1. 检查是否已安装 Tailscale
2. 未安装则安装
3. 如果我提供了 auth key，就用 auth key 加入
4. 如果我没提供 auth key，就执行 tailscale up 并把授权链接返回给我
5. 接入后执行：
   - tailscale status
   - tailscale ip -4
   - tailscale ping 100.100.67.109
   - tailscale ping 100.99.117.43
   - Test-NetConnection 100.100.67.109 -Port 3306
6. 把最终主机名、Tailscale IP 和验证结果告诉我
```

### 14.2 给同事机器上的 Codex

```text
请把当前这台 Windows 机器加入我现有的 Tailscale tailnet。

现有节点：
- DESKTOP-9KO3IVK / 100.100.67.109
- ts-relay-01 / 100.99.117.43
- MagicDNS 后缀：tail6e2c27.ts.net

这台机器属于我的同事，他会用自己的 Tailscale 账号登录。

要求：
1. 检查是否已安装 Tailscale
2. 未安装则安装
3. 执行 tailscale up，并把授权链接打开或返回
4. 等用户完成网页授权后，执行：
   - tailscale status
   - tailscale ip -4
   - tailscale ping 100.100.67.109
   - tailscale ping 100.99.117.43
   - Test-NetConnection 100.100.67.109 -Port 3306
5. 把最终主机名、Tailscale IP 和验证结果告诉我
```

## 15. 不建议做的事

1. 不要把 `3306` 直接暴露到公网
2. 不要多人长期共用 `root`
3. 不要把一次性的 `auth key` 当成长期固定值写死
4. 不要在 `tailscale ping` 都不通时就去改 MySQL

## 16. 后续建议

如果后面这套方案会长期用，建议再做三件事：

1. 为迁移工具和同事各自建立独立 MySQL 账号
2. 把常用重查询改造成汇总表或副本查询
3. 对 `ts-relay-01` 增加简单监控，至少监控 `tailscaled` 和 `UDP 40000`