安装与首次运行：构建、启动日志、第一个请求

本章导读

2.1 引入

部署一个新服务栈，最磨人的往往不是写代码，而是环境准备：Node 要 nvm 和 node_modules，Go 要 toolchain 和 GOPATH，传统 C 服务要自建构建流水线。XServer 的答案是把它全部折叠进构建期与二进制内部：构建时用你的 GCC 编出 xs.exe，同时把 TCC 编译器、全套 SDK 头文件、系统库定义经 LZMA 压缩嵌进二进制；运行期目标机上什么都不需要装。

所以"安装 XServer"实际上是两个动作：构建一次宿主，然后运行一个现成的应用目录（demo-single）。我们从这两个动作开始。

2.2 构建宿主

前置条件只有两个：GCC（可用 --cc 指定）和 Python 3。在 xserver 仓库根目录：

$ build.bat                # 最小变体：default
$ build.bat sqlite xtp     # 编入 SQLite 与 XTP2 扩展
$ build.bat --list-extensions
可选扩展: sqlite, xtp

Linux 下等价命令是 bash build.sh sqlite xtp。构建流水线做了五件事：

最后一步值得强调：链接成功才替换产物。构建失败时，release 目录里的 xs.exe 保持原样——这个"失败保护"有专门的测试用例看护，你在任何时候中断构建都不会得到一个坏二进制。

2.3 运行 demo 与日志解读

demo-single 是仓库自带的完整示例应用（路由、模板、SQLite、受控页面）。进入目录直接运行：

$ cd release/demo-single
$ ./xs.exe
[xs] config loaded: D:\GIT\xserver\release\demo-single/xs.json (1 servers)
[xs] server 'demo' class=http 127.0.0.1:9080 tls=off enabled
[xs]   default-host 'app' path=...\wwwroot devfile=...\main.c
[xs] engine started, workers=12
[xs] script loaded: ...\main.c (2.6 KB gen 1)
[demo] database opened: ...\db\main.db
[xs] server 'demo' http bound on 127.0.0.1:9080
[xs] running, press Ctrl+C to stop

刚才发生了什么——逐行拆开：

2.4 发起请求

另开一个终端，向 demo 发起几个请求（全部为实机输出）：

$ curl -s http://127.0.0.1:9080/json
{"server":"xs3 demo","ok":true,"host":"app"}

$ curl -s http://127.0.0.1:9080/text
demo-single ok (from includes/demo_extra.h)

$ curl -s http://127.0.0.1:9080/api/v1/items/42
{"id":42,"name":"bench-write","created":1788494894}

$ curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:9080/nope
404
$ curl -sI http://127.0.0.1:9080/json
HTTP/1.1 405 Method Not Allowed
Allow: GET

刚才发生了什么：

• /json 走的是应用脚本里的 Handle_JSON——用 xvalue 构造对象后序列化（第 18 章的主题）；
• /api/v1/items/42 命中了动态路由 /api/v1/items/{id}，参数 42 被段捕获后查 SQLite（第 17 章）；
• /nope 未命中任何路由与应用处理，返回 404；
• HEAD /json 得到 405 + Allow: GET——路由方法掩码里只注册了 GET，HEAD 在进入处理器之前就被方法槽拒绝。这是一个真实的路由细节，第 17 章会讲怎么处理 HEAD。

2.5 契约

• 线程线：workers 数在启动时固定，热重载不可变（变更会被拒绝）。
• 变体线：构建变体决定脚本可用的符号——default 变体没有 sqlite3_* / xtp2_*，用了就编译失败。
• 数据线：demo 的 db/main.db 是真实数据文件；练习时随便改，重新构建仓库即可复原。

常见错误

./xs
bind failed
./xs          /* 反复重试，不知道谁占了端口 */

netstat -ano | findstr 9080
/* 改 xs.json 的 port，或结束占用进程 */

copy xs.exe C:\tools\
C:\tools\xs.exe      /* config load failed */

/* xs.json 与源码目录和 exe 放一起；
 * 或显式指定配置路径 */
./xs D:\apps\myapp\xs.json

编程练习