Compare commits
4
Commits
a398bc418d
...
4971077d3b
| Author | SHA1 | Date | |
|---|---|---|---|
 FoXiMao
|
4971077d3b | ||
|
FoXiMao
|
81e5d331ca | ||
|
FoXiMao
|
4f5588ffcb | ||
|
FoXiMao
|
551fe5e5e7 |
@@ -29,7 +29,7 @@
|
||||
<!-- gitnexus:start -->
|
||||
# GitNexus — Code Intelligence
|
||||
|
||||
This project is indexed by GitNexus as **a-share-analysis** (1847 symbols, 2522 relationships, 50 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
|
||||
This project is indexed by GitNexus as **a-share-analysis** (1929 symbols, 2606 relationships, 50 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
|
||||
|
||||
> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
|
||||
|
||||
|
||||
@@ -0,0 +1,377 @@
|
||||
# Tailscale + SSH 隧道访问 TDX 开发手册
|
||||
|
||||
## 1. 用途与适用边界
|
||||
|
||||
本手册用于 Mac 本地开发期间，按需访问家中 Windows 上仅监听回环地址的 TDX HTTP 接口。链路只用于真实字段核验和只读冒烟，不是生产采集、数据上报或公网部署方案。
|
||||
|
||||
```text
|
||||
Mac 本地程序
|
||||
-> 127.0.0.1:17710
|
||||
-> SSH 本地端口转发
|
||||
-> Tailscale 私有网络
|
||||
-> Windows OpenSSH
|
||||
-> Windows 127.0.0.1:17709
|
||||
-> TDX
|
||||
```
|
||||
|
||||
日常开发默认使用仓库内固定样本。只有需要验证 TDX 真实协议和字段时才启动本隧道；Windows 离线不得阻塞普通开发、测试或构建。
|
||||
|
||||
## 2. 安全边界
|
||||
|
||||
- 不在路由器上开放或转发 SSH、RDP、`17709`、`17710` 等端口。
|
||||
- TDX 继续只监听 Windows `127.0.0.1:17709`，不得改为 `0.0.0.0`。
|
||||
- SSH 使用独立 Ed25519 密钥，不在脚本、仓库、文档或远程 URL 中保存密码和私钥。
|
||||
- Mac 转发端口只绑定 `127.0.0.1:17710`，不得绑定局域网或所有网卡。
|
||||
- 真实返回只用于只读验证。日志和测试报告必须脱敏，不保存家庭网络信息、登录信息或无关原始载荷。
|
||||
- 开发隧道不连接生产数据库、不承担生产采集，也不证明数据源具备商业展示或再分发授权。
|
||||
|
||||
文档中的值均为占位符：
|
||||
|
||||
- `<WINDOWS_TAILSCALE_HOST>`：Windows 的 Tailscale MagicDNS 名称或 Tailscale IP。
|
||||
- `<WINDOWS_SSH_USER>`：用于 SSH 登录的 Windows 用户。
|
||||
- `<MAC_TAILSCALE_IP>`：Mac 的 Tailscale IP，仅在收紧防火墙来源时使用。
|
||||
|
||||
## 3. 首次建立 Tailscale 网络
|
||||
|
||||
### 3.1 Mac
|
||||
|
||||
1. 从 Tailscale 官方渠道安装客户端。
|
||||
2. 登录项目使用的同一个 Tailnet。
|
||||
3. 确认菜单栏中的 Tailscale 状态为已连接。
|
||||
4. 在终端检查本机和节点列表：
|
||||
|
||||
```bash
|
||||
tailscale ip -4
|
||||
tailscale status
|
||||
```
|
||||
|
||||
### 3.2 Windows
|
||||
|
||||
1. 从 Tailscale 官方渠道安装客户端。
|
||||
2. 登录与 Mac 相同的 Tailnet。
|
||||
3. 确认 Windows 节点在 Tailscale 管理后台和 Mac 的 `tailscale status` 中均为在线。
|
||||
4. 在 Windows PowerShell 中检查地址和状态：
|
||||
|
||||
```powershell
|
||||
tailscale ip -4
|
||||
tailscale status
|
||||
```
|
||||
|
||||
### 3.3 私网连通验证
|
||||
|
||||
在 Mac 执行：
|
||||
|
||||
```bash
|
||||
tailscale ping <WINDOWS_TAILSCALE_HOST>
|
||||
```
|
||||
|
||||
只有 Tailscale ping 成功后再排查 SSH。不要用公网 IP 替换占位符，也不要为排障临时开放路由器端口。
|
||||
|
||||
## 4. 配置 Windows OpenSSH Server
|
||||
|
||||
以下命令在 Windows 管理员 PowerShell 中执行。
|
||||
|
||||
### 4.1 安装并启动服务
|
||||
|
||||
```powershell
|
||||
Get-WindowsCapability -Online | Where-Object Name -Like 'OpenSSH.Server*'
|
||||
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
|
||||
Start-Service sshd
|
||||
Set-Service -Name sshd -StartupType Automatic
|
||||
Get-Service sshd
|
||||
```
|
||||
|
||||
如果 OpenSSH Server 已安装，`Add-WindowsCapability` 可以跳过。`Get-Service sshd` 应显示服务正在运行且启动类型为自动。
|
||||
|
||||
检查端口监听：
|
||||
|
||||
```powershell
|
||||
Get-NetTCPConnection -LocalPort 22 -State Listen
|
||||
```
|
||||
|
||||
### 4.2 确认防火墙规则
|
||||
|
||||
OpenSSH 安装通常会创建入站规则。先检查，不要重复创建同名规则：
|
||||
|
||||
```powershell
|
||||
Get-NetFirewallRule -Name 'OpenSSH-Server-In-TCP' -ErrorAction SilentlyContinue
|
||||
```
|
||||
|
||||
首次联调可以保留系统创建的 SSH 规则；链路确认后按第 11 节限制为 Tailscale 来源。不得新增公网端口映射。
|
||||
|
||||
## 5. 配置 SSH 密钥登录
|
||||
|
||||
### 5.1 在 Mac 生成项目专用密钥
|
||||
|
||||
```bash
|
||||
ssh-keygen -t ed25519 -a 100 -f ~/.ssh/tdx_windows -C "tdx-windows-development"
|
||||
chmod 600 ~/.ssh/tdx_windows
|
||||
chmod 644 ~/.ssh/tdx_windows.pub
|
||||
pbcopy < ~/.ssh/tdx_windows.pub
|
||||
```
|
||||
|
||||
私钥 `~/.ssh/tdx_windows` 只保留在 Mac，不发送给 Windows，也不提交仓库。建议为私钥设置口令，并由 macOS 钥匙串或 `ssh-agent` 管理。
|
||||
|
||||
### 5.2 Windows 管理员账户
|
||||
|
||||
Windows OpenSSH 默认从 `C:\ProgramData\ssh\administrators_authorized_keys` 读取管理员公钥。必须先创建文件，再设置 ACL；否则 `icacls` 会报“系统找不到指定的文件”。
|
||||
|
||||
在管理员 PowerShell 中执行，按提示粘贴刚复制的单行公钥：
|
||||
|
||||
```powershell
|
||||
$authorizedKeys = "$env:ProgramData\ssh\administrators_authorized_keys"
|
||||
New-Item -ItemType Directory -Force -Path (Split-Path $authorizedKeys)
|
||||
if (-not (Test-Path $authorizedKeys)) {
|
||||
New-Item -ItemType File -Path $authorizedKeys
|
||||
}
|
||||
$publicKey = Read-Host '粘贴 Mac 的单行 SSH 公钥'
|
||||
if (-not (Get-Content $authorizedKeys | Where-Object { $_ -eq $publicKey })) {
|
||||
Add-Content -Path $authorizedKeys -Value $publicKey -Encoding ascii
|
||||
}
|
||||
icacls $authorizedKeys /inheritance:r
|
||||
icacls $authorizedKeys /grant "*S-1-5-18:F" "*S-1-5-32-544:F"
|
||||
Restart-Service sshd
|
||||
```
|
||||
|
||||
`S-1-5-18` 是 SYSTEM，`S-1-5-32-544` 是本地 Administrators 组。使用 SID 可以避免中文 Windows 的组名本地化问题。
|
||||
|
||||
### 5.3 Windows 非管理员账户
|
||||
|
||||
非管理员账户使用用户目录下的 `authorized_keys`。在该登录用户自己的 PowerShell 中执行：
|
||||
|
||||
```powershell
|
||||
$sshDirectory = "$env:USERPROFILE\.ssh"
|
||||
$authorizedKeys = "$sshDirectory\authorized_keys"
|
||||
New-Item -ItemType Directory -Force -Path $sshDirectory
|
||||
if (-not (Test-Path $authorizedKeys)) {
|
||||
New-Item -ItemType File -Path $authorizedKeys
|
||||
}
|
||||
$publicKey = Read-Host '粘贴 Mac 的单行 SSH 公钥'
|
||||
if (-not (Get-Content $authorizedKeys | Where-Object { $_ -eq $publicKey })) {
|
||||
Add-Content -Path $authorizedKeys -Value $publicKey -Encoding ascii
|
||||
}
|
||||
icacls $authorizedKeys /inheritance:r
|
||||
icacls $authorizedKeys /grant "$($env:USERNAME):F"
|
||||
Restart-Service sshd
|
||||
```
|
||||
|
||||
管理员和非管理员两种方式只选与实际账户匹配的一种。若修改了 `C:\ProgramData\ssh\sshd_config`，先执行 `sshd -t` 校验，再重启服务。
|
||||
|
||||
## 6. 配置 Mac SSH 别名
|
||||
|
||||
编辑 Mac 的 `~/.ssh/config`，加入：
|
||||
|
||||
```sshconfig
|
||||
Host tdx-windows
|
||||
HostName <WINDOWS_TAILSCALE_HOST>
|
||||
User <WINDOWS_SSH_USER>
|
||||
IdentityFile ~/.ssh/tdx_windows
|
||||
IdentitiesOnly yes
|
||||
ServerAliveInterval 30
|
||||
ServerAliveCountMax 3
|
||||
ExitOnForwardFailure yes
|
||||
LocalForward 127.0.0.1:17710 127.0.0.1:17709
|
||||
```
|
||||
|
||||
然后修正权限：
|
||||
|
||||
```bash
|
||||
chmod 700 ~/.ssh
|
||||
chmod 600 ~/.ssh/config ~/.ssh/tdx_windows
|
||||
```
|
||||
|
||||
首次连接先验证密钥登录：
|
||||
|
||||
先在 Windows 管理员 PowerShell 查看主机公钥指纹：
|
||||
|
||||
```powershell
|
||||
ssh-keygen -lf "$env:ProgramData\ssh\ssh_host_ed25519_key.pub"
|
||||
```
|
||||
|
||||
再在 Mac 连接，并确认首次连接提示的 Ed25519 指纹与 Windows 输出一致：
|
||||
|
||||
```bash
|
||||
ssh -v tdx-windows
|
||||
```
|
||||
|
||||
预期可以直接登录，或只要求输入私钥口令。若仍要求 Windows 账户密码，重点检查公钥文件位置、ACL、登录账户是否属于 Administrators，以及 SSH 调试输出中实际使用的密钥。
|
||||
|
||||
## 7. 启动和停止隧道
|
||||
|
||||
### 7.1 前台运行
|
||||
|
||||
适合首次验证，按 `Ctrl+C` 停止：
|
||||
|
||||
```bash
|
||||
ssh -N tdx-windows
|
||||
```
|
||||
|
||||
### 7.2 后台运行
|
||||
|
||||
使用独立控制套接字启动，便于精确停止本项目隧道：
|
||||
|
||||
```bash
|
||||
ssh -fN -M -S ~/.ssh/tdx-windows-control tdx-windows
|
||||
ssh -S ~/.ssh/tdx-windows-control -O check tdx-windows
|
||||
```
|
||||
|
||||
停止后台隧道：
|
||||
|
||||
```bash
|
||||
ssh -S ~/.ssh/tdx-windows-control -O exit tdx-windows
|
||||
```
|
||||
|
||||
如果控制套接字残留但进程已不存在，先确认 `17710` 没有监听，再删除该单个套接字文件。不要用宽泛的 `pkill ssh`，以免终止其他 SSH 会话。
|
||||
|
||||
## 8. 验证 TDX 链路
|
||||
|
||||
### 8.1 Windows 本机验证
|
||||
|
||||
先确认 TDX 客户端已启动、已登录，接口监听 `127.0.0.1:17709`：
|
||||
|
||||
```powershell
|
||||
Get-NetTCPConnection -LocalAddress 127.0.0.1 -LocalPort 17709 -State Listen
|
||||
```
|
||||
|
||||
端口没有监听时，应先恢复 TDX 客户端；SSH 和 Tailscale 无法替代 TDX 服务本身。
|
||||
|
||||
### 8.2 Mac 端口验证
|
||||
|
||||
隧道启动后在 Mac 执行：
|
||||
|
||||
```bash
|
||||
nc -vz 127.0.0.1 17710
|
||||
lsof -nP -iTCP:17710 -sTCP:LISTEN
|
||||
```
|
||||
|
||||
`17710` 的监听进程应为本次 SSH 隧道，不应是其他应用。
|
||||
|
||||
### 8.3 只读 HTTP 冒烟
|
||||
|
||||
```bash
|
||||
curl --fail-with-body --silent --show-error \
|
||||
--connect-timeout 3 \
|
||||
--max-time 10 \
|
||||
-H 'Content-Type: application/json' \
|
||||
-X POST 'http://127.0.0.1:17710/' \
|
||||
--data '{"id":1,"method":"get_market_data","params":{"stock_list":["600519.SH"],"count":5,"dividend_type":"none","period":"1d"}}'
|
||||
```
|
||||
|
||||
链路验收条件：HTTP 返回成功，且 TDX 业务响应中的错误码表示成功。只验证少量公开行情，不调用交易、账户、自选、写入或大批量接口。
|
||||
|
||||
## 9. 外网场景验证
|
||||
|
||||
在真正离开家庭网络前，使用 Mac 手机热点或其他外部网络完成一次演练：
|
||||
|
||||
1. 确认 Windows 保持开机、联网，Tailscale 和 `sshd` 在线，TDX 已启动并登录。
|
||||
2. Mac 切换到外部网络后重新连接 Tailscale。
|
||||
3. 执行 `tailscale ping <WINDOWS_TAILSCALE_HOST>`。
|
||||
4. 执行 `ssh -N tdx-windows` 并保持终端运行。
|
||||
5. 依次执行 `nc` 和只读 `curl` 冒烟。
|
||||
6. 停止隧道，确认 `127.0.0.1:17710` 不再监听。
|
||||
|
||||
如果外网演练失败，日常开发继续使用固定样本。不要临时开放公网 SSH、RDP 或 TDX 端口。
|
||||
|
||||
## 10. Windows 无人值守准备
|
||||
|
||||
当前链路是开发辅助，不承诺生产级 7x24 可用性。为了减少外出后无法联调的概率，可在 Windows 上做以下准备：
|
||||
|
||||
- 将虚拟机配置为宿主机启动后自动启动，并确认异常关机后的恢复策略。
|
||||
- 保持 Tailscale 与 `sshd` 服务自动启动，重启后通过另一台 Tailnet 设备验证在线状态。
|
||||
- 接通电源时禁用自动睡眠：
|
||||
|
||||
```powershell
|
||||
powercfg /change standby-timeout-ac 0
|
||||
```
|
||||
|
||||
- 明确 TDX 是否需要交互式桌面登录、验证码或人工确认。需要人工登录时，不得把它描述为无人值守服务。
|
||||
- 安排 Windows 更新和虚拟机重启窗口；更新后重新验证 Tailscale、SSH、TDX 监听和只读请求。
|
||||
- 不为自动启动把 Windows 密码、TDX 凭据或 SSH 私钥写入仓库和普通脚本。
|
||||
|
||||
## 11. 收紧访问范围
|
||||
|
||||
链路验证通过后，在 Tailscale 管理后台将访问规则限制为指定开发身份或 Mac 到 Windows SSH 端口。具体策略应以当前 Tailnet 的身份和标签设计为准，不在仓库保存真实账户和地址。
|
||||
|
||||
还可在 Windows 中新增一条仅允许 Mac Tailscale IP 访问 SSH 的规则。先确认 Tailscale 网卡名称，再创建规则：
|
||||
|
||||
```powershell
|
||||
Get-NetAdapter | Where-Object InterfaceDescription -Match 'Tailscale'
|
||||
New-NetFirewallRule `
|
||||
-DisplayName 'OpenSSH Server - Tailscale Mac Only' `
|
||||
-Direction Inbound `
|
||||
-Action Allow `
|
||||
-Protocol TCP `
|
||||
-LocalPort 22 `
|
||||
-RemoteAddress '<MAC_TAILSCALE_IP>' `
|
||||
-InterfaceAlias 'Tailscale'
|
||||
```
|
||||
|
||||
新规则必须在外网场景实测通过后，才能禁用范围更宽的旧 SSH 规则。若实际网卡别名不是 `Tailscale`，使用 `Get-NetAdapter` 显示的名称，不凭猜测修改。
|
||||
|
||||
## 12. 故障排查
|
||||
|
||||
### Tailscale ping 不通
|
||||
|
||||
- 检查两端是否登录同一个 Tailnet、节点是否过期、Windows 是否睡眠或断网。
|
||||
- 检查 Tailnet ACL 或设备审批状态。
|
||||
- 不要先排查 TDX；此时底层私网尚未连通。
|
||||
|
||||
### SSH 连接超时或拒绝
|
||||
|
||||
- Windows 执行 `Get-Service sshd` 和 `Get-NetTCPConnection -LocalPort 22 -State Listen`。
|
||||
- 检查 Windows 防火墙和 Tailscale 访问规则。
|
||||
- Mac 执行 `ssh -vvv tdx-windows`，确认目标是 Tailscale 地址而非家庭公网地址。
|
||||
|
||||
### SSH 仍要求 Windows 密码
|
||||
|
||||
- 确认 `IdentityFile` 指向 `~/.ssh/tdx_windows`，并检查 `ssh -vvv` 是否提供了该密钥。
|
||||
- 管理员账户确认文件是 `C:\ProgramData\ssh\administrators_authorized_keys`；非管理员账户确认文件是用户目录下的 `.ssh\authorized_keys`。
|
||||
- 确认公钥为完整单行文本，文件已先创建，ACL 没有继承无关权限。
|
||||
- 执行 `sshd -t` 检查配置，再执行 `Restart-Service sshd`。
|
||||
|
||||
### Mac 的 `17710` 无法监听
|
||||
|
||||
- 查看 SSH 前台错误；`ExitOnForwardFailure yes` 会在端口冲突或转发失败时直接退出。
|
||||
- 执行 `lsof -nP -iTCP:17710 -sTCP:LISTEN` 查找占用者。
|
||||
- 不要把本地端口改成 `0.0.0.0`；需要换端口时同步修改本机开发配置，并保持回环绑定。
|
||||
|
||||
### 端口可连但 HTTP 失败
|
||||
|
||||
- 在 Windows 本机确认 TDX `127.0.0.1:17709` 正在监听。
|
||||
- 确认 TDX 客户端已登录且当前版本仍支持目标方法。
|
||||
- 使用最小只读请求检查 HTTP 状态、TDX 错误码和响应时间，不把协议错误误判为网络错误。
|
||||
|
||||
### 外出后 Windows 不在线
|
||||
|
||||
- 无法远程唤醒或恢复交互式 TDX 登录时，切回固定样本继续开发。
|
||||
- 不通过新增公网暴露、共享密码或关闭防火墙绕过问题。
|
||||
- 待公网部署需求明确后，另立功能实现生产级采集器、心跳、补传和远程运维。
|
||||
|
||||
## 13. 日常操作速查
|
||||
|
||||
开始真实 TDX 联调：
|
||||
|
||||
```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
|
||||
nc -vz 127.0.0.1 17710
|
||||
```
|
||||
|
||||
结束联调：
|
||||
|
||||
```bash
|
||||
ssh -S ~/.ssh/tdx-windows-control -O exit tdx-windows
|
||||
lsof -nP -iTCP:17710 -sTCP:LISTEN
|
||||
```
|
||||
|
||||
最后一条命令无输出表示本地转发已经停止。
|
||||
|
||||
## 14. 后续 Provider 接入约束
|
||||
|
||||
- 平台配置只能引用 Mac 回环地址 `127.0.0.1:17710`，不得保存家庭网络地址。
|
||||
- 真实 TDX Provider 必须显式启用；默认仍为确定性的固定样本 Provider。
|
||||
- Provider 必须限制请求超时、响应体大小、股票数量和并发，并输出来源、采集时间、交易日期、协议版本、追踪 ID 和陈旧状态。
|
||||
- TDX 原始字段仅在 Adapter 内转换，上层市场概览、规则分析和 AI 分析只依赖版本化内部契约。
|
||||
- 隧道中断必须返回明确的不可用或陈旧状态，不能把固定样本伪装成实时行情。
|
||||
- Windows 采集器、公网接收 API、多目标推送、补传队列和无人值守运维继续延期，实施时单独立项并重新进行安全、性能和合规评估。
|
||||
@@ -0,0 +1,55 @@
|
||||
# 数据源接入架构与 TDX PoC 规划
|
||||
|
||||
## 方案结论
|
||||
|
||||
当前采用“平台先行、采集器后置”。Mac 本地开发以固定样本回放为默认 Provider；需要验证真实字段时，通过 Tailscale + SSH 隧道访问家中 Windows 的 TDX `127.0.0.1:17709`。不在当前阶段实现 Windows 常驻采集程序、GUI 或公网推送。
|
||||
|
||||
```text
|
||||
固定样本 / Mac TDX 隧道
|
||||
↓
|
||||
DataProvider 端口
|
||||
↓
|
||||
标准化市场事件 → 市场概览业务
|
||||
|
||||
未来公网模式：采集器 → 多目标隔离推送 → 平台接收 API
|
||||
```
|
||||
|
||||
## 方案比较
|
||||
|
||||
- 本地样本回放（当前采用）：不引入 Windows/公网依赖，测试稳定可重复，适合先开发市场概览；缺点是不能代表实时数据质量。
|
||||
- Mac 通过 Tailscale SSH 隧道调用 TDX（当前联调）：可以验证真实字段，但依赖家中 Windows 在线和人工维护。
|
||||
- Windows 常驻采集器（延期）：未来可选 Node、Python、Go、Rust、Electron、Tauri 或系统服务，必须按部署规模、资源、自动更新和安全能力重新评估。
|
||||
|
||||
## 当前组件边界
|
||||
|
||||
当前只新增/维护平台侧 Provider 端口和固定样本。样本 Provider 与真实 TDX Provider 使用同一标准化契约，市场概览不感知来源差异。未来采集器应作为独立项目或 workspace，不反向污染 NestJS 业务模块；公网接收 API、目标队列、签名握手和 GUI 另立功能档案。
|
||||
|
||||
## Provider 与事件模型
|
||||
|
||||
Provider 生成不可变标准化事件，包含 `eventId`、`source`、`capturedAt`、`tradeDate`、`schemaVersion`、`traceId` 和数据新鲜度。TDX 原始字段只能存在于 Adapter 内，规则分析、AI 分析、API 和页面只依赖内部模型。
|
||||
|
||||
## 安全策略与评估
|
||||
|
||||
- Mac 本地样本和 TDX 隧道均不接触生产配置、生产数据库或公网接收 API。
|
||||
- 真实 TDX 只读调用使用 SSH 密钥隧道，`17709`、SSH 和 RDP 不做公网端口映射。
|
||||
- 样本删除凭据、家庭地址和无关原始字段；日志只保存统一错误分类和性能摘要。
|
||||
- 未来采集器的密钥存储、目标认证、IPC 和自动更新不在当前方案中预设，必须重新安全评估。
|
||||
- 数据再分发许可属于外部合规风险。PoC 只用于个人开发验证，不宣称获得商业展示或再分发授权。
|
||||
|
||||
## 性能目标与评估
|
||||
|
||||
- 固定样本回放必须确定性、可重复且不访问网络；Provider 标准化耗时纳入单元测试与基准记录。
|
||||
- 真实 TDX 请求目标超时 5 秒并记录响应耗时和字段完整性。
|
||||
- 公网上传并发、队列容量、心跳周期和 GUI 资源目标延期到采集器立项，不在当前阶段作容量承诺。
|
||||
|
||||
## 失败恢复
|
||||
|
||||
TDX 请求失败返回统一错误分类和陈旧状态；本地平台可切回固定样本继续开发，不能把样本伪装为实时行情。上传重试、补传、熔断和备用免费源切换属于后续公网功能。
|
||||
|
||||
## 测试边界
|
||||
|
||||
单元测试使用固定 TDX 响应验证 Provider、标准化和错误映射；通过 Tailscale SSH 隧道做真实只读冒烟。Electron/Tauri 安装、托盘、开机启动、操作系统密钥存储、目标队列和公网接收测试延期，不能在当前阶段宣称通过。
|
||||
|
||||
## 依赖与退出方案
|
||||
|
||||
当前不新增 Electron、Python、Go、Rust 或其他采集器运行时依赖。未来采集器实现前重新比较语言、部署形态、许可证、资源、自动更新和安全边界；只要遵循 Provider/上传契约，采集器可替换而不改市场概览。
|
||||
@@ -0,0 +1,26 @@
|
||||
# GitNexus 开发前基线
|
||||
|
||||
- 功能编号：FEAT-DS-001
|
||||
- 记录时间：2026年8月14日 GMT+8 02:38:03
|
||||
- 分支：main
|
||||
- 基线提交：a398bc418d39
|
||||
|
||||
## 工作区
|
||||
|
||||
```text
|
||||
?? docs/features/FEAT-DS-001-tdx-ingestion-poc/
|
||||
```
|
||||
|
||||
## GitNexus 状态
|
||||
|
||||
```text
|
||||
Repository: /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis
|
||||
Indexed: 8/14/2026, 2:38:02 AM
|
||||
Indexed commit: a398bc4
|
||||
Current commit: a398bc4
|
||||
Status: ✅ up-to-date
|
||||
```
|
||||
|
||||
## 后续人工分析
|
||||
|
||||
在修改代码前，将 GitNexus query、context、impact 的结论写入 `gitnexus/impact-plan.md`。高风险结果必须先获得用户确认。
|
||||
@@ -0,0 +1,24 @@
|
||||
# GitNexus 开发前影响计划
|
||||
|
||||
- 功能编号：FEAT-DS-001
|
||||
- 总体风险：LOW（当前仅规划 Provider 边界和本地联调，不新增桌面应用或公网入口）
|
||||
|
||||
## 直接与间接影响
|
||||
|
||||
- `gitnexus query --repo a-share-analysis "market data ingestion TDX adapter scheduler worker"` 未找到现成行情 Provider，相关现有流程集中在 Scheduler/Worker 启动和运行时配置。
|
||||
- `gitnexus query --repo a-share-analysis "configuration HTTP API health Redis MySQL RocketMQ"` 表明 API 当前只有健康检查流程，新增接收模块不会修改 `HealthService`。
|
||||
- 对名称 `health` 的 upstream impact 命中 Web API 目录且风险为 LOW、无上游消费者；由于名称存在歧义，结论仅作为辅助证据，不解释为对 API 全局无影响。
|
||||
- 当前不新增 `desktop/tdx-agent` 或 `MarketIngestModule`，不会修改现有 Web、API、Scheduler 或 Worker 符号。
|
||||
- 直接消费者是后续市场概览 Service；未来采集器、RocketMQ Worker、Redis 快照和 MySQL 历史属于延期功能，必须重新执行影响分析。
|
||||
|
||||
## 跨模块同步修改
|
||||
|
||||
- HTTP/OpenAPI：当前不新增公网握手或上报 DTO；Provider 内部契约不得泄漏到 Web。
|
||||
- Web API：主平台 Vue 不修改；不存在 Electron renderer。
|
||||
- 消息契约：本 PoC 不启用 RocketMQ，也不预留伪接收实现。
|
||||
- 数据库与 Redis：不新增 Schema，不读取生产库；PoC 接收仅做受控确认。
|
||||
- API：后续 Provider 如进入 API，再对 `ApiModule.register`、OpenAPI 和运行时配置执行影响分析。
|
||||
- Scheduler/Worker：本 PoC 不修改；后续正式排队功能另立功能档案和影响分析。
|
||||
- 配置部署：当前不新增 Windows 或公网配置，不改变主平台源码部署政策。
|
||||
- 测试：使用固定样本和 TDX 隧道冒烟；采集器打包和 Windows 无人值守测试延期。
|
||||
- 文档：记录延期原因、Provider 边界、安全、性能和未来重新立项条件。
|
||||
@@ -0,0 +1,17 @@
|
||||
# 数据源接入架构与 TDX PoC 规划
|
||||
|
||||
## 当前计划（不实现采集器）
|
||||
|
||||
1. 建立与运行时无关的 `DataProvider`、市场事件和数据新鲜度契约。
|
||||
2. 用固定样本 Provider 支撑市场概览的规则、AI、混合和对照分析开发。
|
||||
3. 按 [Tailscale + SSH 隧道访问 TDX 开发手册](../../deployment/tailscale-tdx-development.md) 执行真实 TDX 只读请求，保存脱敏字段报告。
|
||||
4. 对 TDX 字段缺失、协议错误和陈旧数据做 Provider 层降级，不连接生产数据。
|
||||
5. 暂不新增 Windows 应用、Electron/Tauri、目标推送、补传队列、公网接收 API、RocketMQ 事件或数据库表。
|
||||
6. 待公网部署需求确定后，另立采集器功能档案，重新评估 Node、Python、Go、Rust 或系统服务方案。
|
||||
|
||||
## 后置功能必须覆盖
|
||||
|
||||
- 单次采集、多目标隔离推送。
|
||||
- production/development 独立地址、密钥、队列、状态和启停；两者地址均可修改。
|
||||
- production 未配置或停止为正常状态；停止时不删除队列、不转投 development。
|
||||
- HTTPS/HMAC、重放防护、握手身份、限流、补传、熔断、心跳、无人值守运行和系统更新。
|
||||
@@ -0,0 +1,12 @@
|
||||
id: FEAT-DS-001
|
||||
name: 数据源接入架构与 TDX PoC 规划
|
||||
slug: tdx-ingestion-poc
|
||||
status: deferred
|
||||
owner: project
|
||||
created_at: 2026-08-14
|
||||
requirements: requirements.md
|
||||
prd: prd.md
|
||||
design: design.md
|
||||
implementation_plan: implementation-plan.md
|
||||
traceability_note: 当前只完成数据源边界和本地联调规划；操作步骤见 ../../deployment/tailscale-tdx-development.md；Windows 采集器与公网接入延期到公网部署需求确认后单独立项。
|
||||
release: unreleased
|
||||
@@ -0,0 +1,37 @@
|
||||
# TDX 数据接入 PoC PRD
|
||||
|
||||
## 用户问题
|
||||
|
||||
TDX 客户端运行在家中 Windows 虚拟机，并且接口只监听 Windows 本机 `127.0.0.1:17709`。公网平台和人在外面的开发设备都不能直接访问该端口，需要验证一套不暴露 TDX、可 7×24 小时运行的数据上报链路。
|
||||
|
||||
## 目标
|
||||
|
||||
在不提前引入公网部署和 Windows 常驻程序的前提下，先确定 TDX 数据源边界、标准化 Provider 契约和 Mac 本地联调方式。Windows 采集器、托盘 GUI、目标推送和公网接收入口延期，避免在生产部署形态尚未确定时锁定技术栈。
|
||||
|
||||
## 范围
|
||||
|
||||
- Mac 本地开发使用固定样本回放作为默认数据源，并保留通过 Tailscale SSH 隧道调用家中 Windows TDX 的人工联调方式。
|
||||
- 只定义与运行时无关的 `DataProvider`、标准化事件和数据新鲜度字段，不实现 Windows 常驻采集程序。
|
||||
- 记录未来公网模式的单次采集、多目标隔离推送、地址可变和目标启停原则，但不在本功能实现。
|
||||
- 只读验证指数、单股 K 线、快照、分时和板块接口中实际可用的字段。
|
||||
- 通过 Tailscale + SSH 隧道从外部 Mac 远程验证家中 Windows TDX；验证结果只用于 Provider 契约，不写入生产链路。
|
||||
|
||||
## 非目标
|
||||
|
||||
- 不在本功能中开发 Windows 采集应用、Electron/Tauri GUI、开发/生产接收 API、目标队列或公网推送。
|
||||
- 不在本功能中开发市场概览页面、AI 分析、正式 Worker 消费或生产接入。
|
||||
- 不开放 TDX `17709`、SSH 或 RDP 到公网。
|
||||
- 不写入自选、交易、账户或 TDX 状态。
|
||||
- 不把通达信数据授权问题解释为已解决；商业展示和再分发授权仍需单独确认。
|
||||
|
||||
## 成功指标
|
||||
|
||||
- 固定样本能够覆盖 Provider 的 K 线、快照、分时、板块和错误映射测试。
|
||||
- 通过 SSH 隧道完成至少一次真实 TDX 只读请求，并保存脱敏字段报告。
|
||||
- Provider 契约不依赖 Node、Electron、Python 或具体传输方式；未来采集器可独立替换。
|
||||
|
||||
## 风险
|
||||
|
||||
- TDX 客户端协议和返回字段可能变化；代理必须保留原始字段版本和来源标识。
|
||||
- 未来公网部署会增加采集节点、推送认证和再分发风险；延期期间不把这些风险误标为已解决。
|
||||
- 行情数据的展示、再分发和商业使用权利不由代码许可证自动授予。
|
||||
@@ -0,0 +1,28 @@
|
||||
# 数据源接入架构与 TDX PoC 工程需求
|
||||
|
||||
## 当前阶段 Provider 边界
|
||||
|
||||
- Provider 暴露与采集器语言和传输方式无关的只读接口，统一返回 `source`、`capturedAt`、`tradeDate`、`schemaVersion`、`traceId` 和数据新鲜度。
|
||||
- 默认开发 Provider 使用仓库内固定样本，不连接生产数据源；真实 TDX Provider 只通过显式本地配置和 Tailscale SSH 隧道联调。
|
||||
- TDX Provider 限制回环地址、请求超时、响应体大小、股票列表和并发；不得把家庭地址或凭据写入代码。
|
||||
- Provider 原始响应映射为版本化内部载荷，上层分析不得依赖 TDX 原始字段名称。
|
||||
|
||||
## 当前运行与环境
|
||||
|
||||
- 平台仅在 Mac 本地源码运行，不要求安装 Windows 采集程序。
|
||||
- 固定样本支持离线、确定性和可重复测试；真实 TDX 联调依赖家中 Windows 在线，但不能成为日常测试门禁。
|
||||
- 当前不新增 Electron、Tauri、Python 服务、Go/Rust 程序、公网接收 API、文件补传队列或目标密钥。
|
||||
- SSH 私钥、TDX 地址、家庭网络信息和开发数据库凭据不得进入仓库、日志、样本或前端构建物。
|
||||
|
||||
## 延期的公网采集原则
|
||||
|
||||
- 采集器语言、GUI 壳和打包方式不预设为 Node/Electron，待公网部署需求确认后比较 Node、Python、Go、Rust 和系统服务方案。
|
||||
- 未来采集器只采集一次，production/development 使用独立地址、节点 ID、密钥、队列、上传器、心跳和启停状态。
|
||||
- production 与 development 地址均可修改且独立测试；任一目标故障或重配不得影响另一目标。
|
||||
- production 未配置或停止属于正常状态；停止时不删除已有队列、不转投 development。
|
||||
- 公网模式必须重新设计 HTTPS/HMAC、重放防护、身份握手、限流、补传、熔断、无人值守运行和操作系统密钥存储。
|
||||
|
||||
## 可观测性
|
||||
|
||||
- Provider 结果标记来源、采集时间、数据时间、陈旧状态和统一错误分类。
|
||||
- 真实联调报告必须脱敏，不保存完整家庭地址、SSH 信息、供应商凭据或未筛选的原始载荷。
|
||||
@@ -0,0 +1,23 @@
|
||||
# 数据源接入架构与 TDX PoC 测试计划
|
||||
|
||||
## 当前阶段功能验证
|
||||
|
||||
- 固定样本验证 K 线、快照、分时和板块 Provider 载荷映射。
|
||||
- 通过 Tailscale SSH 隧道验证真实 TDX 只读请求，并保存脱敏字段报告。
|
||||
- 验证 Provider 在 TDX 错误、超时、空结果和陈旧数据下返回统一错误分类。
|
||||
- 验证市场概览只依赖内部模型，不直接读取 TDX 原始字段。
|
||||
|
||||
## 安全验证
|
||||
|
||||
- SSH 私钥、TDX 地址、家庭网络信息和开发数据库凭据不进入仓库、样本、日志或前端构建物。
|
||||
- TDX 只通过 SSH 隧道访问，`17709` 不开放公网。
|
||||
- 固定样本不包含供应商凭据和不必要的完整原始载荷。
|
||||
|
||||
## 性能验证
|
||||
|
||||
- 固定样本下测量 Provider 标准化耗时，确保回放不依赖外部网络。
|
||||
- 真实 TDX 请求记录响应耗时和字段完整性；不对未来采集器的上传、队列和 GUI 资源作结论。
|
||||
|
||||
## 不适用项与边界
|
||||
|
||||
不做 Electron/Tauri 窗口、托盘、安装包、生产数据库迁移、RocketMQ 收发和公网接收验证，原因是采集器与公网部署已延期。市场概览页面另按业务功能执行视觉验证。
|
||||
@@ -19,6 +19,7 @@
|
||||
## 环境与部署
|
||||
|
||||
- [本地开发环境](deployment/local-development.md)
|
||||
- [Tailscale + SSH 隧道访问 TDX 开发手册](deployment/tailscale-tdx-development.md)
|
||||
- [Ubuntu 源码生产部署（唯一生产方式）](deployment/ubuntu-source-production.md)
|
||||
|
||||
## 数据库版本基线
|
||||
@@ -36,6 +37,7 @@
|
||||
|
||||
- [GOV-001：工程治理基线](features/GOV-001-engineering-governance/manifest.yaml)
|
||||
- [FEAT-MO-001：市场综合概览](features/FEAT-MO-001-market-overview/manifest.yaml)
|
||||
- [FEAT-DS-001：数据源接入架构与 TDX PoC 规划（采集器延期）](features/FEAT-DS-001-tdx-ingestion-poc/manifest.yaml)
|
||||
- [GOV-002：PRD 与 Review 门禁](features/GOV-002-prd-review-gates/manifest.yaml)
|
||||
- [GOV-003：项目专用 Gitea 远程仓库](features/GOV-003-gitea-local-remote/manifest.yaml)
|
||||
- [GOV-004：提交后强制推送 Gitea](features/GOV-004-mandatory-gitea-push/manifest.yaml)
|
||||
|
||||
Reference in New Issue
Block a user