FoXiMao/a-share-analysis
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(FEAT-MO-001): 记录 TDX 双场景开发接入

Browse Source
This commit is contained in:
FoXiMao
2026-08-18 00:32:04 +08:00
parent c0a6f55605
commit 998c9276d5
4 changed files with 189 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/deployment/tailscale-tdx-development.md
+99 -35
View File
@@ -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、多目标推送、补传队列和无人值守运维继续延期，实施时单独立项并重新进行安全、性能和合规评估。
docs/features/FEAT-MO-001-market-overview/gitnexus/before.md
+31
View File
@@ -0,0 +1,31 @@
# GitNexus 开发前基线
- 功能编号：FEAT-MO-001
- 记录时间：2026年08月18日 00:26:46 CST
- 分支：main
- 基线提交：`c0a6f5560584`
- 创建方式：用户授权跳过 `v0.0.9` Schema 备份后，按 `governance:start` 输出结构手工留痕
## 工作区
```text
(干净)
```
## GitNexus 状态
```text
Repository: /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis
Indexed: 8/17/2026, 6:03:13 PM
Indexed commit: c0a6f55
Current commit: c0a6f55
Status: up-to-date
```
## Schema 门禁例外
失败证据、用户决定、禁止伪造边界和残余风险见 `../schema-baseline-waiver.md`。本记录不表示 `governance:start` 自动门禁通过。
## 后续人工分析
首页设计确认后，在修改任何函数、类或方法前继续执行 GitNexus query、context 和 upstream impact，并将直接、间接、跨模块消费者及高风险处置补充到 `impact-plan.md`。
docs/features/FEAT-MO-001-market-overview/gitnexus/impact-plan.md
+36
View File
@@ -0,0 +1,36 @@
# GitNexus 开发前影响计划
- 功能编号：FEAT-MO-001
- 基线提交：`c0a6f5560584`
- 当前阶段：TDX 开发连接设计与首页方案确认
- 当前总体风险：LOW（仅本机 SSH 配置和操作文档）；首页业务代码风险待设计确认后按符号补充
## 直接与间接影响
### TDX 双路径开发连接
- 正式行情来源确定为 TDX；家庭局域网和外部 Tailscale 只改变 Mac 到同一 Windows `sshd` 的网络路径。
- TDX Bridge 的稳定入口固定为 Mac 回环地址 `127.0.0.1:17710`，市场概览、规则分析、AI 分析和未来 HTTP 契约不得依赖家庭地址、Tailscale 地址或 TDX 原始字段。
- 当前仓库没有 TDX Provider 或市场概览运行时符号，本阶段只更新操作文档；GitNexus 未识别可执行调用链影响。
- 首页业务设计确认后，必须对 `App.vue`、`createAppRouter`、后端模块装配、HTTP DTO 和新增市场概览符号分别执行 upstream impact。HIGH 或 CRITICAL 结果先告知用户再修改。
## 跨模块同步修改
- HTTP/OpenAPI：当前连接文档不修改；首页正式接入时需要版本化市场概览 DTO 与 OpenAPI 契约。
- Web API 与 adapter：当前不修改；未来页面只能经 `web/src/api/<业务域>/index.ts`、Axios 封装和 ViewModel 消费数据。
- 消息契约、Redis、MySQL、Scheduler、Worker：当前不启用。正式采集链路仍按独立功能立项，不能由 API 请求临时抓取全市场数据。
- 配置部署：真实地址、用户名、密钥和控制套接字只保留在开发机，不进入仓库、环境模板或前端构建物。
- 测试：两种 SSH 路径均需验证到同一 Mac 回环端点；离线样本只作显式开发回退，不得标记为实时 TDX。
- 文档：同步更新 Tailscale/SSH 开发手册，明确家庭局域网与外部 Tailscale 的选择、启动、停止、切换和验证方法。
## 安全、性能与回退
- Windows 的 TDX 继续只监听 `127.0.0.1:17709`，禁止改为局域网或公网监听。
- 家庭 SSH 入站规则只允许家庭子网访问 TCP 22；系统原有全范围 OpenSSH 规则保持禁用。
- 两条 SSH 路径复用同一项目专用 Ed25519 密钥；局域网主机密钥必须与已验证的 Tailscale 主机密钥指纹一致。
- 家庭 LAN 与当前 Tailscale 直连延迟均足以满足开发期分钟级行情；首页不得承诺秒级刷新。
- 回退时停止对应 SSH 控制连接、删除本机 TDX 别名，并删除 Windows 项目专用防火墙规则；不得删除通用 SSH 密钥、Tailscale 账户或 TDX 数据。
## Schema 例外风险
`v0.0.9` Schema 基线缺失会阻断严格自动治理门禁，风险见 `../schema-baseline-waiver.md`。本功能不借该例外修改数据库结构、读取生产数据库或声称发布门禁通过。
docs/features/FEAT-MO-001-market-overview/schema-baseline-waiver.md
+23
View File
@@ -0,0 +1,23 @@
# v0.0.9 Schema 基线一次性例外
- 功能编号：FEAT-MO-001
- 日期：2026-08-18
- 适用范围：仅 FEAT-MO-001 开发启动
## 事实记录
按常规流程执行 `npm run schema:baseline` 时，本机因不存在 MySQL 5.7.x 的 `mysql` 与 `mysqldump` 客户端，在执行 `mysql --version` 前以 `spawnSync mysql ENOENT` 失败。失败发生在客户端前置检查阶段，未连接开发数据库，也未生成基线目录或半成品。
用户确认本次继续跳过数据库备份。该决定只适用于从已发布版本 `v0.0.9` 启动 FEAT-MO-001，不继承 GOV-011 对 `v0.0.8` 的一次性例外，也不建立通用跳过能力。
## 处理决定
- 不伪造 `not_applicable`、`captured_empty`、空 SQL、客户端版本、服务端版本或校验摘要。
- 不修改 Schema 工具或 `governance:start` 增加跳过参数。
- 手工保存与 `governance:start` 同等结构的 GitNexus 开发前基线和影响计划。
- FEAT-MO-001 不得因此连接、探测或读取生产数据库。
- 后续功能需要 Schema 基线时，仍必须提供可验证的 MySQL 5.7.x 客户端，或再次获得用户针对该版本的明确授权。
## 风险与接受
缺少 `v0.0.9` Schema 基线意味着仓库不能证明该发布版本对应的开发库结构，也会使依赖严格 Schema 证据的自动治理门禁无法通过。用户接受本次追溯风险；该例外不表示数据库门禁、发布门禁或未来数据库变更已经通过。