第 48 章 / 共 51 章
卷五 · 扩展、运维与实战
单文件发布
xs 的名字里写着"单文件"——这一章兑现它：把配置、静态站、C 源码、TLS 证书全部打进一个 exe，拷走即部署。
本章导读
站位：部署形态的终点。前面所有章节的应用（xs.json + 源码 + wwwroot + 证书）在此收敛为一个文件——站点 VFS（应用包）附加在 xs 二进制末尾，无参启动自动识别。实机验证标签的输出均来自打包后 exe 的真实运行。
48.1 打包与运行
xs 自带打包子命令——不需要任何外部工具（无 Python 依赖）：
实机验证 · pack 三步
# 打包（站点目录须含 xs.json；基底 = 当前运行的 xs 自身）
xs.exe pack site/ -o app.exe
[pack] base 6202368 bytes + 30 files, compressing...
[pack] 30/30 compressed
[pack] app.exe: 30 entries (lzma 28, store 2), archive 575363 bytes
# 部署：把这一个文件拷到目标机，无参启动
app.exe
[xs] app pack: 30 entries
[xs] config loaded: app-pack:xs.json (1 servers)
[xs] http host 'site' static root '...\wwwroot' on disk missing, serving from app pack压缩是逐条 LZMA（无收益自动 STORE）——demo 站 1.7 MB 文本压到 542 KB。配 webview 扩展（第 14 库）组合，产物就是"双击即用的桌面应用"。
48.2 磁盘优先：热修免重打包
单文件模式的文件读取规则只有一条：磁盘赢，包内兜底。
| 场景 | 磁盘 wwwroot/ | 结果 |
|---|---|---|
| 纯包 | 不存在 | 全部条目走包内（pRoot 为空路径） |
| 热修 | 空目录 + 覆盖文件 | 覆盖文件走磁盘，其余包内兜底 |
| 恢复 | 删覆盖文件 | 该文件自动恢复包内版本 |
证书同理：续签后把新 cert.pem 放到 exe 旁即生效——路径读取走统一出口（磁盘优先、包内兜底），程序写文件后包内旧文件自然作废。搭配
xsTlsRefresh（证书热替换 API）即全自动续签闭环。注意：磁盘覆盖场景要求 wwwroot 目录在启动时已存在（静态根句柄一次性打开）——启动前建好空目录即可。
48.3 工具链与调试
实机验证 · pack 工具四命令
xs pack --list app.exe # 条目清单（方法/大小/CRC/路径）
xs pack --extract app.exe -d out/ # 解包取证（diff 与源站逐字节一致）
xs pack --strip app.exe -o orig.exe # 还原原始二进制（cmp 字节级相同）
app.exe --no-vfs # 忽略应用包，回目录模式调试归档格式四级 CRC 校验（尾标 → 归档头 → 索引 → 条目解压后），损坏包在装载期即拒绝。重复打包自动剥旧包（CRC 确认后剥，防误剥无关二进制）。格式逐字段规格见仓库 docs/站点VFS设计.md。
48.4 内存与线程模型
- 索引：启动装载一次，不可变——多 worker 并发二分查找无锁
- 内容：首次访问惰性解压并常驻缓存（demo 全站 1.7 MB 封顶；冷文件永不占内存）
- 压缩数据区：不进内存——按偏移从 exe 文件读，热度交给 OS 文件缓存
- 启动开销：探测读自身末尾 24 字节，无包零成本
常见错误
坑：磁盘覆盖不生效wwwroot 目录必须在启动时存在（静态根句柄一次性打开）——启动前 mkdir 一个空目录，运行期投递的文件才能被磁盘层看到。
坑：重打包后体积翻倍pack 自动剥旧包，但如果基底 exe 本身已带包且 CRC 校验失败会当无包处理——用 --strip 先还原，或确认基底是干净构建产物。
坑：dev_inc 找不到头文件包内源码头挂载在 /xs/site/<相对路径> 虚拟根下；dev_inc 的绝对路径自动剥 appPath 前缀映射——检查 pack --list 里条目路径与配置一致（大小写敏感）。
编程练习
基础
把卷二配套的静态站打包，用 --list 确认条目数，再 --strip 还原后 cmp 验证字节一致。
进阶
打包后在 exe 旁放一个覆盖 index.html，验证磁盘优先与删除恢复（三场景循环）。
验收
用 openssl 自签证书进包，启动 https 服务并用 curl -k 验证证书从包内解压（提示：见第 12 章）。
小结速查
pack site/ -o app.exe = 单文件部署 · 磁盘赢包内兜 = 热修免重打包 · --list / --extract / --strip = 内建工具 · --no-vfs = 目录模式调试 · 逐条 LZMA + 四级 CRC = 格式底线