# A股基本面研究工作台 — 小主机部署记录

## 一、当前状态

| 项目 | 状态 |
| --- | --- |
| 项目目录 | `C:\FundamentalWorkbench` |
| 本地服务 | `http://127.0.0.1:8765/reports/dashboard/index.html` （运行中） |
| 公网地址 | 见 `C:\FundamentalWorkbench\deploy\public_url.txt` （临时隧道，**每次重启都会变**） |
| 数据快照 | 看板 as-of `2026-09-11`，因子 as-of `2026-08-31` |
| 开机自启 | 已配置（用户登录后自动启动，含崩溃自动重启） |

## 二、目录说明

```
C:\FundamentalWorkbench\
├─ reports\dashboard\index.html   看板主页（数据内嵌，自包含）
├─ serve_dashboard.py             本地 HTTP 服务（127.0.0.1:8765）
├─ vendor\                        隔离依赖（Python 3.12 Windows x64）
├─ data\processed\                数据产物
└─ deploy\                        本次部署新增
   ├─ start_dashboard_server.ps1  看板服务，崩溃每 5 秒重试，最多 5 次
   ├─ start_tunnel.ps1            cloudflared 公网隧道，崩溃每 5 秒重试
   ├─ launch_*_hidden.cmd         无窗口启动包装
   ├─ autostart.vbs               开机自启入口
   ├─ public_url.txt              当前公网地址
   └─ logs\                       运行日志
```

## 三、开机自启

已把 `deploy\watchdog.vbs` 放入用户「启动」文件夹：

```
C:\Users\Luka\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\FundamentalWorkbenchWatchdog.vbs
```

`watchdog.vbs` 每 60 秒轮询一次：看板服务和隧道**哪个不在就拉起哪个**，
所以单次崩溃、被误杀、或其中一个先崩，都能在 1 分钟内自愈，不必等重新登录。

**重要限制：** 启动文件夹只在**用户登录后**执行。若主机重启后停在登录界面，看门狗本身不会启动，服务也不会起来。
两种解决办法：

1. 配置 Windows 自动登录（推荐，最简单）：`netplwiz` → 取消勾选「要使用本计算机，用户必须输入用户名和密码」→ 输入密码。需要管理员权限。
2. 用管理员权限注册开机计划任务（不依赖登录）：
   ```powershell
   powershell -ExecutionPolicy Bypass -File C:\FundamentalWorkbench\deploy\install_tasks.ps1
   ```
   该任务使用 S4U（无需保存密码），需要以管理员身份运行一次。

## 四、常用运维命令

查看当前公网地址：
```powershell
Get-Content C:\FundamentalWorkbench\deploy\public_url.txt
```

查看服务是否在跑：
```powershell
Get-NetTCPConnection -State Listen -LocalPort 8765
Get-Process cloudflared, python
```

查看日志：
```powershell
Get-Content C:\FundamentalWorkbench\deploy\logs\dashboard_server.log -Tail 20
Get-Content C:\FundamentalWorkbench\deploy\logs\tunnel.log -Tail 20
```

手动重启服务（先杀进程，自启脚本会自动拉起；或重新运行 vbs）：
```powershell
wscript.exe C:\FundamentalWorkbench\deploy\autostart.vbs
```

停止服务：
```powershell
Get-Process python, cloudflared -ErrorAction SilentlyContinue | Stop-Process -Force
```

## 五、待办事项（尚未完成，需要你决定）

### 1. 临时隧道不是长期方案
当前用的是 Cloudflare 快速隧道（`trycloudflare.com`），没有可用性保证，**重启后地址会变**。
长期建议二选一：
- **Tailscale**（本机已安装，未登录）：适合只有你自己设备访问，最安全，地址固定。
- **Cloudflare 命名隧道**：需要 Cloudflare 账号 + 域名，公网固定网址，可加登录验证。

### 2. 日更数据目前无法运行
日更依赖本机**通达信（TDX）数据目录**，原项目配置指向 `D:/Software/TDX64` 和 `E:/Codex_量化/...`。
这台小主机**没有 D: / E: 盘**，所以 `run_daily_update.cmd` 会因缺少数据源而失败。
需要先做其中一件：
- 把通达信装到本机并下载完整沪深日线、专业财务、除权除息数据，然后重新配置路径：
  ```powershell
  powershell -ExecutionPolicy Bypass -File C:\FundamentalWorkbench\scripts\configure_host.ps1 -TdxRoot "D:\Software\TDX64"
  C:\FundamentalWorkbench\run_daily_update.cmd --check
  ```
- 或者只把本机当**展示机**，数据更新在原机器上做完后，把 `data\` 和 `reports\` 同步过来。

### 3. 安全提醒
看板**没有任何登录验证**，拿到地址的人可以看到全部数据。临时隧道地址是随机长串，不易被猜到，但一旦分享出去就等于公开。若要长期公开访问，务必加验证。

## 六、环境检查结果（`run_daily_update.cmd --check`）

按运维提示词要求执行的只读环境检查，退出码 `1`，`ready=false`，**当前不可接管日更**。

| 字段 | 实测值 |
| --- | --- |
| `ready` | `false` |
| `python` | `C:\Users\Luka\AppData\Local\Programs\Python\Python312\python.exe` |
| `pythonVersion` | `3.12.10` ✅ 符合 3.12 系列要求 |
| `projectRoot` | `C:\FundamentalWorkbench` |
| `missingModules` | `["pyarrow", "duckdb"]` ❌ |
| `missingPaths` | `[]` ✅ |
| `missingSourcePaths` | `D:\Software\TDX64`、`\vipdoc\sh\lday`、`\vipdoc\sz\lday`、`\vipdoc\cw`、`T0002\hq_cache\gbbq` ❌ |
| `warnings` | 「历史名称辅助目录不存在（可选）：`E:\Codex_量化\Codex历史文件\bt\data`」——属提示词所列“可选历史名称目录缺失”类警告，不是失败 |

### 两个独立缺口

**缺口 A：依赖缺失（`DEPENDENCY_MISSING`）**
`requirements.txt` 声明了 `pyarrow>=15` 和 `duckdb>=1.0`，但发布包的 `vendor\`
里**没有打进这两个包**（`vendor\pandas\compat\pyarrow.py` 只是 pandas 的兼容层，不是 pyarrow）。
系统 Python 3.12 也未安装它们。因此**即使配好通达信路径，日更仍会因缺依赖失败**。
按提示词规定安装依赖属人工操作，本次未执行。补齐方式：

```powershell
& 'C:\Users\Luka\AppData\Local\Programs\Python\Python312\python.exe' -m pip install pyarrow duckdb --target C:\FundamentalWorkbench\vendor
```

**缺口 B：数据源缺失（`SOURCE_NOT_READY`）**
本机无 D: 盘，通达信目录不存在，`config\local_paths.toml` 仍是打包机器的路径。
需要人工安装通达信并重新配置：

```powershell
powershell -ExecutionPolicy Bypass -File C:\FundamentalWorkbench\scripts\configure_host.ps1 -TdxRoot '<实际通达信目录>'
```

在 `ready=true` 之前，按提示词第 3.1 节**不得运行正式日更**。

## 七、本次部署验证记录

- 解压 3259 个文件到 `C:\FundamentalWorkbench`（0.72 GB）
- 本地服务：`HTTP 200`，1,003,733 字节
- 公网可达性：连续 13 次请求全部 `HTTP 200`（经 Cloudflare 边缘节点）
- 崩溃恢复实测：手动杀掉 python 与 cloudflared 进程后，两项服务均在 60 秒内自动恢复
- 看门狗实测：同时杀掉两个服务，`watchdog.vbs` 在 80 秒内把两者都重新拉起
- 第二轮更新包（`..._141804.zip`）比对：除新增 `prompts/deepseek_workbench_manager.md` 外，
  其余 3259 个文件与上一包**逐字节一致**（`reports/dashboard/index.html` SHA-256 均为
  `0968d4a7…312f49`），看板数据无变化，无需重新部署
- 自启脚本实测：通过 `autostart.vbs` 完整拉起服务成功

### 排查记录
初版启动脚本含中文注释，未带 BOM 的 UTF-8 文件被 Windows PowerShell 5.1 按 ANSI 解析，
导致字符串终止符报错、脚本启动即失败。已将 `deploy\` 下所有 `.ps1`/`.cmd`/`.vbs` 改为纯 ASCII，
可用 `[System.Management.Automation.Language.Parser]::ParseFile` 复验语法。