From 758dafeab0836ad6a8959bb3fefcdcaeb69a67d8 Mon Sep 17 00:00:00 2001
From: cai <cai@nbcai.cc>
Date: Thu, 02 Jul 2026 23:48:23 +0800
Subject: [PATCH] docs: add Tailscale MySQL middleware guide
---
middleware/Tailscale-MySQL-统一落地手册.md | 570 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 570 insertions(+), 0 deletions(-)
diff --git "a/middleware/Tailscale-MySQL-\347\273\237\344\270\200\350\220\275\345\234\260\346\211\213\345\206\214.md" "b/middleware/Tailscale-MySQL-\347\273\237\344\270\200\350\220\275\345\234\260\346\211\213\345\206\214.md"
new file mode 100644
index 0000000..4a298f9
--- /dev/null
+++ "b/middleware/Tailscale-MySQL-\347\273\237\344\270\200\350\220\275\345\234\260\346\211\213\345\206\214.md"
@@ -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`
--
Gitblit v1.9.3