docs(FEAT-MO-001): 记录 TDX 双场景开发接入
This commit is contained in:
@@ -2,19 +2,19 @@
|
||||
|
||||
## 1. 用途与适用边界
|
||||
|
||||
本手册用于 Mac 本地开发期间，按需访问家中 Windows 上仅监听回环地址的 TDX HTTP 接口。链路只用于真实字段核验和只读冒烟，不是生产采集、数据上报或公网部署方案。
|
||||
本手册用于 Mac 本地开发期间，访问家中 Windows 上仅监听回环地址的 TDX HTTP 接口。TDX 是市场概览的正式行情来源；SSH 隧道负责把家庭局域网和外部 Tailscale 两种开发位置统一成同一个 Mac 回环入口。该链路不是生产采集、数据上报或公网部署方案。
|
||||
|
||||
```text
|
||||
Mac 本地程序
|
||||
Mac 本地程序 / TDX Bridge
|
||||
-> 127.0.0.1:17710
|
||||
-> SSH 本地端口转发
|
||||
-> Tailscale 私有网络
|
||||
-> Windows OpenSSH
|
||||
-> 家庭局域网或 Tailscale 私有网络
|
||||
-> 同一台 Windows OpenSSH
|
||||
-> Windows 127.0.0.1:17709
|
||||
-> TDX
|
||||
```
|
||||
|
||||
日常开发默认使用仓库内固定样本。只有需要验证 TDX 真实协议和字段时才启动本隧道；Windows 离线不得阻塞普通开发、测试或构建。
|
||||
两个场景只切换 SSH 目标别名，TDX Bridge 和上层业务始终访问 `http://127.0.0.1:17710/`。离线样本只允许作为显式开发和自动化测试回退，并必须标记为离线数据；不得伪装为实时 TDX。Windows 离线不得阻塞普通测试或构建。
|
||||
|
||||
## 2. 安全边界
|
||||
|
||||
@@ -157,20 +157,34 @@ Restart-Service sshd
|
||||
|
||||
管理员和非管理员两种方式只选与实际账户匹配的一种。若修改了 `C:\ProgramData\ssh\sshd_config`，先执行 `sshd -t` 校验，再重启服务。
|
||||
|
||||
## 6. 配置 Mac SSH 别名
|
||||
## 6. 配置 Mac SSH 双场景别名
|
||||
|
||||
编辑 Mac 的 `~/.ssh/config`，加入：
|
||||
家庭局域网和外部 Tailscale 连接同一台 Windows、同一个账户和同一个 `sshd`，复用同一把项目专用密钥，不创建第二把 SSH 密钥。编辑 Mac 的 `~/.ssh/config`，加入：
|
||||
|
||||
```sshconfig
|
||||
Host tdx-windows
|
||||
HostName <WINDOWS_TAILSCALE_HOST>
|
||||
Host tdx-windows-lan tdx-windows-tailnet
|
||||
User <WINDOWS_SSH_USER>
|
||||
IdentityFile ~/.ssh/tdx_windows
|
||||
IdentitiesOnly yes
|
||||
UseKeychain yes
|
||||
AddKeysToAgent yes
|
||||
ServerAliveInterval 30
|
||||
ServerAliveCountMax 3
|
||||
ExitOnForwardFailure yes
|
||||
LocalForward 127.0.0.1:17710 127.0.0.1:17709
|
||||
|
||||
Host tdx-windows-lan
|
||||
HostName <WINDOWS_LAN_HOST>
|
||||
|
||||
Host tdx-windows-tailnet
|
||||
HostName <WINDOWS_TAILSCALE_HOST>
|
||||
```
|
||||
|
||||
真实局域网地址、Tailscale 地址和用户名只保存在本机 SSH 配置，不写入仓库。开发代理需要核对当前配置时使用：
|
||||
|
||||
```bash
|
||||
ssh -G tdx-windows-lan | awk '/^(hostname|user|identityfile|localforward) / {print}'
|
||||
ssh -G tdx-windows-tailnet | awk '/^(hostname|user|identityfile|localforward) / {print}'
|
||||
```
|
||||
|
||||
然后修正权限：
|
||||
@@ -191,37 +205,70 @@ ssh-keygen -lf "$env:ProgramData\ssh\ssh_host_ed25519_key.pub"
|
||||
再在 Mac 连接，并确认首次连接提示的 Ed25519 指纹与 Windows 输出一致：
|
||||
|
||||
```bash
|
||||
ssh -v tdx-windows
|
||||
ssh -v tdx-windows-tailnet
|
||||
```
|
||||
|
||||
预期可以直接登录，或只要求输入私钥口令。若仍要求 Windows 账户密码，重点检查公钥文件位置、ACL、登录账户是否属于 Administrators，以及 SSH 调试输出中实际使用的密钥。
|
||||
|
||||
## 7. 启动和停止隧道
|
||||
## 7. 两种场景的选择、启动和停止
|
||||
|
||||
### 7.1 前台运行
|
||||
### 7.1 选择规则
|
||||
|
||||
适合首次验证，按 `Ctrl+C` 停止：
|
||||
| 当前场景 | 使用别名 | 前置条件 |
|
||||
|---|---|---|
|
||||
| Mac 与 Windows 位于已配置的家庭局域网 | `tdx-windows-lan` | Windows 在线、TDX 已登录、家庭 LAN 的 SSH 22 可达 |
|
||||
| Mac 在外部网络，或家庭 LAN SSH 不可达 | `tdx-windows-tailnet` | Mac 与 Windows 的 Tailscale 均在线，Tailnet ping 成功 |
|
||||
|
||||
两种隧道不能同时启动，因为都会独占 Mac `127.0.0.1:17710`。在家庭网络内优先使用 LAN；若 LAN 前置检查失败，不修改 TDX 监听地址，改用 Tailscale。
|
||||
|
||||
### 7.2 家庭局域网模式
|
||||
|
||||
前置检查：
|
||||
|
||||
```bash
|
||||
ssh -N tdx-windows
|
||||
ssh -o BatchMode=yes -o ClearAllForwardings=yes -T tdx-windows-lan exit
|
||||
```
|
||||
|
||||
### 7.2 后台运行
|
||||
仓库文档不保存真实地址，家庭路径直接通过 SSH 别名验证。首次连接必须核对局域网地址与已信任的 Tailscale 地址返回相同 Windows 主机密钥指纹。
|
||||
|
||||
使用独立控制套接字启动，便于精确停止本项目隧道：
|
||||
后台启动和检查：
|
||||
|
||||
```bash
|
||||
ssh -fN -M -S ~/.ssh/tdx-windows-control tdx-windows
|
||||
ssh -S ~/.ssh/tdx-windows-control -O check tdx-windows
|
||||
ssh -fN -M -S ~/.ssh/tdx-windows-lan-control tdx-windows-lan
|
||||
ssh -S ~/.ssh/tdx-windows-lan-control -O check tdx-windows-lan
|
||||
```
|
||||
|
||||
停止后台隧道：
|
||||
停止：
|
||||
|
||||
```bash
|
||||
ssh -S ~/.ssh/tdx-windows-control -O exit tdx-windows
|
||||
ssh -S ~/.ssh/tdx-windows-lan-control -O exit tdx-windows-lan
|
||||
```
|
||||
|
||||
如果控制套接字残留但进程已不存在，先确认 `17710` 没有监听，再删除该单个套接字文件。不要用宽泛的 `pkill ssh`，以免终止其他 SSH 会话。
|
||||
Windows 的家庭 SSH 防火墙规则应使用项目专用名称 `A-Share-TDX-SSH-LAN`，只允许家庭子网访问 TCP 22。系统原有的全范围 OpenSSH 入站规则保持禁用，不为 TDX 开放 `17709`。
|
||||
|
||||
### 7.3 外部 Tailscale 模式
|
||||
|
||||
前置检查：
|
||||
|
||||
```bash
|
||||
tailscale up
|
||||
tailscale ping <WINDOWS_TAILSCALE_HOST>
|
||||
```
|
||||
|
||||
后台启动和检查：
|
||||
|
||||
```bash
|
||||
ssh -fN -M -S ~/.ssh/tdx-windows-tailnet-control tdx-windows-tailnet
|
||||
ssh -S ~/.ssh/tdx-windows-tailnet-control -O check tdx-windows-tailnet
|
||||
```
|
||||
|
||||
停止：
|
||||
|
||||
```bash
|
||||
ssh -S ~/.ssh/tdx-windows-tailnet-control -O exit tdx-windows-tailnet
|
||||
```
|
||||
|
||||
如果控制套接字残留但进程已不存在，先确认 `17710` 没有监听，再删除对应场景的单个控制套接字。不要用宽泛的 `pkill ssh`，以免终止其他 SSH 会话。
|
||||
|
||||
## 8. 验证 TDX 链路
|
||||
|
||||
@@ -266,11 +313,11 @@ curl --fail-with-body --silent --show-error \
|
||||
1. 确认 Windows 保持开机、联网，Tailscale 和 `sshd` 在线，TDX 已启动并登录。
|
||||
2. Mac 切换到外部网络后重新连接 Tailscale。
|
||||
3. 执行 `tailscale ping <WINDOWS_TAILSCALE_HOST>`。
|
||||
4. 执行 `ssh -N tdx-windows` 并保持终端运行。
|
||||
4. 执行 `ssh -N tdx-windows-tailnet` 并保持终端运行。
|
||||
5. 依次执行 `nc` 和只读 `curl` 冒烟。
|
||||
6. 停止隧道，确认 `127.0.0.1:17710` 不再监听。
|
||||
|
||||
如果外网演练失败，日常开发继续使用固定样本。不要临时开放公网 SSH、RDP 或 TDX 端口。
|
||||
如果外网演练失败，开发和自动化测试可显式切换到离线样本，并明确标记数据来源。不要临时开放公网 SSH、RDP 或 TDX 端口。
|
||||
|
||||
## 10. Windows 无人值守准备
|
||||
|
||||
@@ -320,7 +367,7 @@ New-NetFirewallRule `
|
||||
|
||||
- Windows 执行 `Get-Service sshd` 和 `Get-NetTCPConnection -LocalPort 22 -State Listen`。
|
||||
- 检查 Windows 防火墙和 Tailscale 访问规则。
|
||||
- Mac 执行 `ssh -vvv tdx-windows`，确认目标是 Tailscale 地址而非家庭公网地址。
|
||||
- Mac 执行 `ssh -vvv tdx-windows-tailnet`，确认目标是 Tailscale 地址而非家庭公网地址。
|
||||
|
||||
### SSH 仍要求 Windows 密码
|
||||
|
||||
@@ -343,35 +390,52 @@ New-NetFirewallRule `
|
||||
|
||||
### 外出后 Windows 不在线
|
||||
|
||||
- 无法远程唤醒或恢复交互式 TDX 登录时，切回固定样本继续开发。
|
||||
- 无法远程唤醒或恢复交互式 TDX 登录时，显式切回离线样本继续开发，并保持非实时标记。
|
||||
- 不通过新增公网暴露、共享密码或关闭防火墙绕过问题。
|
||||
- 待公网部署需求明确后，另立功能实现生产级采集器、心跳、补传和远程运维。
|
||||
|
||||
## 13. 日常操作速查
|
||||
|
||||
开始真实 TDX 联调：
|
||||
### 13.1 在家开发
|
||||
|
||||
```bash
|
||||
tailscale ping <WINDOWS_TAILSCALE_HOST>
|
||||
ssh -fN -M -S ~/.ssh/tdx-windows-control tdx-windows
|
||||
ssh -S ~/.ssh/tdx-windows-control -O check tdx-windows
|
||||
ssh -o BatchMode=yes -o ClearAllForwardings=yes -T tdx-windows-lan exit
|
||||
ssh -fN -M -S ~/.ssh/tdx-windows-lan-control tdx-windows-lan
|
||||
ssh -S ~/.ssh/tdx-windows-lan-control -O check tdx-windows-lan
|
||||
nc -vz 127.0.0.1 17710
|
||||
```
|
||||
|
||||
结束联调：
|
||||
结束家庭局域网联调：
|
||||
|
||||
```bash
|
||||
ssh -S ~/.ssh/tdx-windows-control -O exit tdx-windows
|
||||
ssh -S ~/.ssh/tdx-windows-lan-control -O exit tdx-windows-lan
|
||||
lsof -nP -iTCP:17710 -sTCP:LISTEN
|
||||
```
|
||||
|
||||
最后一条命令无输出表示本地转发已经停止。
|
||||
### 13.2 在外开发
|
||||
|
||||
```bash
|
||||
tailscale up
|
||||
tailscale ping <WINDOWS_TAILSCALE_HOST>
|
||||
ssh -fN -M -S ~/.ssh/tdx-windows-tailnet-control tdx-windows-tailnet
|
||||
ssh -S ~/.ssh/tdx-windows-tailnet-control -O check tdx-windows-tailnet
|
||||
nc -vz 127.0.0.1 17710
|
||||
```
|
||||
|
||||
结束外部联调：
|
||||
|
||||
```bash
|
||||
ssh -S ~/.ssh/tdx-windows-tailnet-control -O exit tdx-windows-tailnet
|
||||
lsof -nP -iTCP:17710 -sTCP:LISTEN
|
||||
```
|
||||
|
||||
最后一条命令无输出表示本地转发已经停止。切换场景时必须先停止当前隧道，再启动另一场景；不得通过更换 TDX Bridge 地址绕过端口冲突。
|
||||
|
||||
## 14. 后续 Provider 接入约束
|
||||
|
||||
- 平台配置只能引用 Mac 回环地址 `127.0.0.1:17710`，不得保存家庭网络地址。
|
||||
- 真实 TDX Provider 必须显式启用；默认仍为确定性的固定样本 Provider。
|
||||
- 平台配置只能引用 Mac 回环地址 `127.0.0.1:17710`，不得保存家庭网络或 Tailscale 地址。
|
||||
- TDX 是正式行情来源；离线样本只作为显式开发和测试回退，必须展示来源与陈旧状态，生产环境禁止启用。
|
||||
- Provider 必须限制请求超时、响应体大小、股票数量和并发，并输出来源、采集时间、交易日期、协议版本、追踪 ID 和陈旧状态。
|
||||
- TDX 原始字段仅在 Adapter 内转换，上层市场概览、规则分析和 AI 分析只依赖版本化内部契约。
|
||||
- 隧道中断必须返回明确的不可用或陈旧状态，不能把固定样本伪装成实时行情。
|
||||
- 隧道中断必须返回明确的不可用或陈旧状态，不能把离线样本伪装成实时行情。
|
||||
- Windows 采集器、公网接收 API、多目标推送、补传队列和无人值守运维继续延期，实施时单独立项并重新进行安全、性能和合规评估。
|
||||
|
||||
Reference in New Issue
Block a user