# Windows 一键本地运行

v0.6：使用根目录 run-sale-windows.cmd 或 scripts/run-sale-windows.ps1 启动发售与二级交易，-Middleware 使用 PG/Redis/RabbitMQ；完整步骤见[发售手动验收](../04-testing/sale-acceptance.md)。本轮已实际验证该新入口、原生 Windows Go 全包和购买后交易 UI。前次审阅发现的目录同步、恢复进程和静态路径问题已修复，见[实现报告](../reports/2026-11-02-sale-v0.6.md)。Windows 目录同步不等价于 Unix 断电保证；旧模拟入口的历史结果仍以原报告为准。

> 当前基线：模拟 v0.3 保留，独立链模式升级为 v0.5。新增完整历史查询、任务版本保护、已确认事件索引、只读对账和基础告警，见 [设计](../07-history/v0.5-design.md)、[执行报告](../reports/2026-10-12-v0.5.md)。历史报告与证据保留原版本。

> 历史 v0.4 变更记录（当前增量见页首 v0.5）：新增独立run-web3-windows.cmd与scripts/run-web3-windows.ps1，在bin/windows-web3准备Windows专属Anvil/frontend依赖；钱包页面8081、Anvil8545、链31337。原模拟pinkode入口保留；新脚本未在原生Windows实测，步骤见链模式开发手册。 当前链实现见[v0.5架构](../07-history/v0.5-design.md)，操作见[开发](../03-development/web3-development.md)、[测试](../04-testing/web3-testing.md)、[部署](web3-deployment.md)，证据见[本轮报告](../reports/2026-10-12-v0.4.md)。


更新：2026-10-11。在 Windows 文件资源管理器中，双击项目根目录的 [run-windows.cmd](../../run-windows.cmd)。无需 WSL、Docker 或管理员权限；需要 Windows PowerShell 5.1（系统自带）、Go 和 Node.js 22+，首次联网下载依赖与 go.mod 要求的 Go 1.26.9 工具链。

## 使用步骤

1. 安装 Go 与 Node.js 22+，重新打开终端，让 PATH 生效。已有 Go 允许自动下载项目匹配工具链；脚本明确使用 GOTOOLCHAIN=auto。
2. 双击 `run-windows.cmd`。窗口依次检查环境、准备依赖、构建前端与 Windows 服务、初始化本地管理员；就绪后自动打开 http://127.0.0.1:8080。
3. 登录账号 **pinkode**，密码 **2312a132**。页面也接受内部邮箱 pinkode@localhost；账号显示/用户查询保留邮箱身份。
4. 保持启动窗口打开。按 Ctrl+C 停止服务；重跑保留管理员、普通用户、订单和资金，不删除数据或修改已有管理员密码。

如果自动开浏览器失败，可以手动访问窗口输出的 URL。任何依赖/编译/启动失败都会显示原始错误，CMD 窗口保留供阅读，不显示假成功。

## 参数与文件位置

```powershell
# 端口占用时使用另一个本地端口；脚本不会替你关闭已有服务。
.\run-windows.cmd -Port 18080
# 不自动打开浏览器。
.\run-windows.cmd -NoBrowser
# 只安装依赖和构建，不初始化数据、不启动服务。
.\run-windows.cmd -PrepareOnly
# 可选独立演示目录，路径包含空格时加引号。
.\run-windows.cmd -DataDir "D:\exchange demo data"
```

| 文件/目录 | 用途 |
| --- | --- |
| run-windows.cmd | 双击入口；引用脚本使用绝对且带引号的路径，不依赖启动工作目录 |
| scripts/run-windows.ps1 | PowerShell 流程；UTF-8 BOM/CRLF 兼容 Windows PowerShell 5.1 与中文路径 |
| bin/windows/exchange.exe | 每次启动重新编译的原生 Windows 服务，不使用 Linux bin/exchange |
| bin/windows/frontend | Windows 前端源码副本、专属 node_modules 和 dist |
| bin/windows/api/openapi.json | 同次前端构建的契约副本，api:check 校验生成类型一致 |
| data-windows | 默认三库/锁/日志持久目录，独立于 README 的 data/，已加入 .gitignore |

Windows esbuild/rollup 依赖不能直接复用 WSL 的 node_modules；脚本把前端复制到 bin/windows/frontend，锁摘要变化或缺失安装标志时执行 npm ci，每次检查契约并重建 dist。原 frontend/node_modules 与 Linux 构建产物不会被 Windows npm 改写。窗口通过本次子进程 ready 检查后才开页面，不启动第二个 Vite 服务。

脚本只设进程级环境，退出后恢复原值。明确固定回环监听、HTTP Cookie、准确 Origin 和默认资源预算，诊断默认关闭；不能继承云模板的 Secure=true 或外部 Origin 导致本地登录失败。

## 本地管理员的业务边界

常规注册/BootstrapAdmin 仍要求 12–72 UTF-8 字节；指定密码为 8 字节，因此脚本显式启用 EXCHANGE_LOCAL_ADMIN_NAME=pinkode，可信本地初始化允许 8–72 字节。bcrypt 仍加盐哈希，登录/会话/CSRF/RBAC 与普通系统相同，公开注册不会放宽或提权。

服务在打开数据目录前检查这个模式：必须监听数值回环 IP（127.0.0.1 或 ::1），拒绝 0.0.0.0、空 host、非本地地址和常规 EXCHANGE_ADMIN_EMAIL 混用。别名只在该模式的登录 handler 映射为 name@localhost；默认服务不接受无邮箱格式的账号。常规云/容器部署不启用该模式，不使用本地数据目录。

已有 ADMIN 保持原密码；同邮箱已有 USER 则拒绝提权。首次初始化模式与身份可能因失败只完成部分，重跑通过固定 CREDIT 键补齐初始 10 ETH/100000 USDT，不重复增发。普通用户仍用邮箱注册。

## 常见问题

| 提示 | 处理 |
| --- | --- |
| Missing go.exe/node.exe/npm.cmd | 安装 Go/Node，确认 PATH，关闭旧终端再打开 |
| Node.js 22 or newer is required | 更新 Node，脚本支持 22 及更高版本 |
| 首次下载缓慢/失败 | 查看 go mod download/npm ci 原错误，检查网络/代理，再重跑；脚本不自动修改全局代理 |
| Port ... is already in use | 关闭你自己原服务，或用 -Port 18080；不删除数据锁绕过互斥 |
| data directory already in use | 同数据目录只能运行一个服务，先正常停止原实例 |
| 密码无效 | 新目录首次初始化用本文密码；已有管理员不会因脚本变化自动重置密码，核对实际 DataDir |
| 编译 exchange.exe 被拒绝 | 旧进程仍在使用同一个 exe，先停止它；不强杀无关进程或覆盖正在运行产物 |
| Readiness timeout | 查窗口启动/重放错误，历史量大时恢复可能更慢；已提交日志仍保存，不能删 journal/auth 解决 |

正常 Ctrl+C 共享控制台信号让 Go 排空，脚本给子进程 65s 退出窗口，超出后只停止本次创建的进程。强制关闭窗口/任务管理器结束进程仍属于非正常退出，依赖 FULL 日志重放，不冒充优雅关闭或断电验证。

本轮真实验证与限制见[Windows 启动报告](../reports/2026-10-11-windows-launcher.md)，其余维护见[数据生命周期](data-lifecycle.md)与[排障手册](operations-runbook.md)。

## v0.5 Windows 范围

run-windows.cmd 的 pinkode 管理员和模拟数据不变。run-web3-windows.cmd 会构建当前 Web3History 页面与 Go 链模块，仍是独立钱包/测试资产。要观察指标可在运行前设置 WEB3_DIAGNOSTICS_ADDR=127.0.0.1:9091；脚本对旧任务执行兼容迁移，不能复用重建 Anvil 的旧任务。Windows 原生执行仍需该平台复查，WSL 构建不算原生证据。
