Static Web Server 2.44.1 常用 CLI 命令详解

目标：作为 Static Web Server（SWS）的日常操作速查手册——从版本查看、参数启动、配置加载，到 systemd 管控、优雅停机与故障排查的完整命令链。每条命令均在 Ubuntu 22.04 LTS（x86_64）+ SWS v2.44.1 环境实测，回显逐行照录。

一、环境信息

操作系统：Ubuntu 22.04 LTS（x86_64）
软件版本：Static Web Server v2.44.1（官方 musl 二进制，/usr/local/bin/static-web-server；版本查询日期 2026-10-20）
服务形态：systemd 托管（unit 名 static-web-server.service），监听 0.0.0.0:8780
站点根目录：/var/www/html，配置文件：/etc/static-web-server/static-web-server.toml
安装与环境变量文件说明：见本专栏《Ubuntu 22.04 安装 Static Web Server 指南》

二、工具概览

SWS 是单二进制程序，CLI 即服务器本体：没有 start/stop/reload 子命令，执行二进制 = 启动服务；进程常驻由 systemd 负责管理。命令体系仅两层：

主命令参数（约 45 个选项）：设置监听、目录、日志、压缩、认证等，与 TOML 配置文件、SERVER_* 环境变量一一对应（优先级与键名对照见本专栏《Static Web Server 2.44.1 配置参数详解》3.1 节）；
generate 子命令：生成 shell 补全（bash/zsh/fish/PowerShell/nushell）与 man 手册页。

需要特别注意的三个行为特性：

无配置打印命令：没有 config dump 之类命令，生效配置靠 -g info 启动日志逐项核对；
默认日志几乎静默：log-level 默认 error，交互排障记得加 -g info；
前台运行：二进制默认前台阻塞运行（日志尾行 press ctrl+c to shut down the server），生产环境必须由 systemd（或等价进程管理器）托管。

三、前置条件

SWS 已安装：which static-web-server 返回 /usr/local/bin/static-web-server（安装方法见本专栏安装指南）；
8780 端口未被占用：ss -ltn | grep 8780 无输出；
systemd 环境可用：systemctl is-system-running 返回 running 或 degraded。

四、各命令详解

4.1 版本与构建信息（--version / -V）

static-web-server --version

实测回显：

Version:      2.44.1
Built:        2026-10-07 21:53:43 +02:00
Git commit:   c5cbe67e91da91ccad838163cf9a034bf221a447
Build target: x86_64-unknown-linux-musl
Rust version: rustc 1.99.0 (b940084d7 2026-09-28)
License:      MIT OR Apache-2.0
Homepage:     https://static-web-server.net
Author:       Jose Quintana <https://joseluisq.net>

比一般工具的 --version 信息量大：Build target 可确认 musl/gnu 构建变体，Rust version 用于核对工具链要求（2.44.1 需 rustc ≥ 1.88.0，从源码编译时先看这个），Git commit 可与 GitHub Release 页比对确认二进制未被人替换。短选项 -V 等价。

4.2 帮助（--help / -h）

static-web-server --help | head -20

实测回显：

Static Web Server 2.44.1
Jose Quintana <https://joseluisq.net>
Static Web Server (SWS) is a tiny and ultra-fast cross-platform web server to serve static production-ready files

Usage: static-web-server [OPTIONS] [COMMAND]

Commands:
  generate  Generate man pages and shell completions
  help      Print this message or the help of the given subcommand(s)

Options:
  -a, --host <HOST>
          Host address ([::] default: IPV6 all interfaces; `0.0.0.0` IPV4 all interfaces)

          [env: SERVER_HOST=]
          [default: ::]
  -p, --port <PORT>
          Host port

          [env: SERVER_PORT=]
          [default: 80]

--help 与 -h 输出相同（完整约 420 行，覆盖全部参数、默认值与环境变量名）。每个参数下方 [env: SERVER_XXX=] 标注对应的环境变量、[default: ...] 标注内置默认值——这是查阅默认值最权威的途径，官方文档站可能滞后于实际版本。

4.3 参数启动（最小前台服务）

开发调试或临时共享目录时直接参数启动：

static-web-server -a 0.0.0.0 -p 8780 -d /var/www/html -g info

实测回显（前台日志，节选）：

2026-10-20T16:15:34.844974915Z  INFO static_web_server::server: static-web-server 2.44.1
2026-10-20T16:15:34.845019379Z  INFO static_web_server::server: server bound to tcp socket 0.0.0.0:8780
2026-10-20T16:15:34.845021244Z  INFO static_web_server::server: runtime worker threads: 12
2026-10-20T16:15:34.845062803Z  INFO static_web_server::directory_listing: directory listing: enabled=false
2026-10-20T16:15:34.845101602Z  INFO static_web_server::compression: auto compression: enabled=true, formats=deflate,gzip,brotli,zstd, compression level=Default
2026-10-20T16:15:34.845104133Z  INFO static_web_server::control_headers: cache control headers: enabled=true
2026-10-20T16:15:34.845182536Z  INFO static_web_server::server: http1 server is listening on http://0.0.0.0:8780
2026-10-20T16:15:34.845185492Z  INFO static_web_server::server: press ctrl+c to shut down the server

四个参数覆盖 90% 临时需求：-a 监听地址、-p 端口、-d 站点目录、-g 日志级别。请求日志随访问实时输出（INFO static_web_server::log_addr: incoming request: method=GET uri=/）。Ctrl+C 或 kill 后进程退出，长驻服务请用 4.6 的 systemd 方式。

4.4 配置文件加载（--config-file / -w）

生产环境推荐配置文件启动（SWS 默认还会在工作目录找 sws.toml，但显式指定绝对路径最稳妥）：

static-web-server --config-file /etc/static-web-server/static-web-server.toml

实测回显（-g info 下可确认加载的配置文件）：

2026-10-20T16:42:37.403205336Z  INFO static_web_server::server: config file used: /etc/static-web-server/static-web-server.toml
2026-10-20T16:42:37.403317738Z  INFO static_web_server::mem_cache::cache: in-memory cache (experimental): enabled=false
2026-10-20T16:42:37.403390593Z  INFO static_web_server::server: http1 server is listening on http://0.0.0.0:8780

SERVER_* 环境变量与参数等价（如 SERVER_PORT=8780 ↔ -p 8780），systemd 场景下写进 EnvironmentFile 更干净。注意配置文件中的显式键优先级高于 CLI/环境变量（实测与源码依据见配置参数详解篇 3.1 节），排查「参数不生效」先看配置文件有没有写同名键。

4.5 generate 子命令（补全与 man 页）

static-web-server generate /tmp/sws-gen --completions --man-pages
ls -R /tmp/sws-gen

实测回显：

generated shell completions at /tmp/sws-gen/static-web-server.bash (bash)
generated shell completions at /tmp/sws-gen/static-web-server.fish (fish)
generated shell completions at /tmp/sws-gen/static-web-server.zsh (zsh)
generated shell completions at /tmp/sws-gen/static-web-server_nushell.nu (nushell)
generated shell completions at /tmp/sws-gen/static-web-server.ps1 (powershell)
generated man page at /tmp/sws-gen/static-web-server.1
/tmp/sws-gen:
static-web-server.1  static-web-server.bash  static-web-server.fish  static-web-server.ps1  static-web-server_nushell.nu  static-web-server.zsh

启用 bash 补全（新开 shell 生效后可 Tab 补全参数）：

cp /tmp/sws-gen/static-web-server.bash /etc/bash_completion.d/

man 页安装到系统手册（/tmp/sws-gen/static-web-server.1），man static-web-server 即可离线查阅全部参数说明，无外网环境时这是唯一完整的参数文档。

4.6 systemd 管控命令

安装指南 4.6 节创建 unit 文件后，日常管控命令与实测回显：

systemctl daemon-reload                       # unit 文件变更后必须执行
systemctl enable static-web-server            # 开机自启
systemctl start static-web-server             # 启动
systemctl is-active static-web-server         # 状态确认
systemctl status static-web-server --no-pager -l | head -6

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/static-web-server.service → /etc/systemd/system/static-web-server.service.
active
● static-web-server.service - Static Web Server
     Loaded: loaded (/etc/systemd/system/static-web-server.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2026-10-20 16:18:32 UTC; 2s ago
       Docs: https://static-web-server.net
   Main PID: 3024 (static-web-serv)
      Tasks: 13 (limit: 94371)

日常高频操作：

systemctl restart static-web-server   # 配置文件修改后重启生效（SWS 不支持热加载）
systemctl stop static-web-server      # 停止（走优雅停机流程）
journalctl -u static-web-server -f    # 实时跟踪日志

⚠️ ps 中进程名显示为 static-web-serv（Linux 进程名 15 字符截断），写监控或过滤规则时别用全名精确匹配。

4.7 信号与优雅停机（SIGTERM / SIGINT）

SWS 捕获 SIGTERM/SIGINT 执行优雅停机：停止接收新请求 → 等待存量请求完成（上限 grace-period 秒，默认 0）→ 退出。实测宽限期 2 秒的完整日志（systemctl stop 触发）：

2026-10-20T16:38:30.652415834Z  INFO static_web_server::signals: grace period of 2s after the SIGTERM started
2026-10-20T16:38:32.653652113Z  INFO static_web_server::signals: grace period has elapsed
2026-10-20T16:38:32.653689717Z  INFO static_web_server::signals: delegating server's graceful shutdown

要点：宽限期从收到 SIGTERM 起算（grace period of 2s after the SIGTERM started），到点即退出（grace period has elapsed）；实测 systemctl stop 总耗时 2.005 秒。手工操作等价命令 kill -TERM <PID>（kill <PID> 默认即 SIGTERM）；不要用 kill -9，会跳过优雅停机直接掐断在途请求。grace-period 参数上限 255 秒。

4.8 日常运维组合命令

确认端口监听与进程归属（实测回显）：

ss -ltnp | grep 8780
ps aux | grep static-web-server | grep -v grep

LISTEN 0      128          0.0.0.0:8780      0.0.0.0:*    users:(("static-web-serv",pid=4653,fd=9))
www-data    4653  0.0  0.0 1084108 13076 ?       Ssl  16:38   0:00 /usr/local/bin/static-web-server

进程以 www-data（UID 33）运行即符合生产基线；RSS 13076 kB 约 12.8MB，为空载基线内存（开启内存缓存后略增）。

服务健康三连（实测回显）：

systemctl is-active static-web-server
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8780/health
journalctl -u static-web-server --no-pager -n 5 -o cat | grep -E "listening|error"

active
200
2026-10-20T16:31:10.123222702Z  INFO static_web_server::server: http1 server is listening on http://0.0.0.0:8780

请求验证（压缩/缓存/状态码）：

curl -sI http://127.0.0.1:8780/ | head -8
curl -s -o /dev/null -w "%{http_code}\n" -H "Accept-Encoding: gzip" http://127.0.0.1:8780/index.html

实测回显：

HTTP/1.1 200 OK
content-length: 170
content-type: text/html; charset=utf-8
accept-ranges: bytes
last-modified: Tue, 20 Oct 2026 16:15:29 GMT
vary: accept-encoding
cache-control: max-age=86400
date: Tue, 20 Oct 2026 16:15:43 GMT
200

参数写错时（实测回显，退出码 2）：

static-web-server --nonexistent-flag

error: unexpected argument '--nonexistent-flag' found

Usage: static-web-server [OPTIONS] [COMMAND]

脚本中判断启动成功与否可用 static-web-server --version >/dev/null; echo $?（正常退出码 0）。

五、注意事项

前台阻塞是默认行为：直接跑二进制会占住终端，日志还几乎静默（error 级）；交互测试务必加 -g info，常驻服务交给 systemd。
配置文件优先于 CLI 参数：-p 8781 不会覆盖配置文件里的 port = 8780（实测依据见配置参数详解篇 3.1），混合使用两种来源时以配置文件为准排查。
SIGHUP 不会重读配置：修改 TOML 后唯一生效方式是 systemctl restart（或重启进程）。
进程名截断：static-web-server 的进程名在 ps/ss 中显示为 static-web-serv，pkill -x static-web-server 全称精确匹配会失配——杀进程按 kill <PID> 最可靠。
默认监听 IPv6 全地址：--host 默认 ::（同时兼容 IPv4）；若仅需 IPv4 显式 -a 0.0.0.0。绑定 80/443 特权端口需 systemd 托管（root 拉起后降权）或官方 socket activation（--fd）。
--version 是部署校验的最后一道关：版本号、Build target、Git commit 三字段齐全才算部署正确，缺一说明二进制来路有问题。

六、常见问题（FAQ）

Q1：执行命令后终端没有输出、像卡住了？

正常现象——SWS 前台常驻运行且默认 log-level = error 无日志输出。加 -g info 重跑可见完整启动日志与请求日志；确认服务活着可另开终端 curl -I http://127.0.0.1:8780/。

Q2：启动报 Address in use (os error 98)？

端口被占。先用 ss -ltnp | grep <端口> 找占用者：常见原因是手工实例与 systemd 实例各跑了一份（ps aux | grep static-web-server 有多行）。按 PID kill 掉多余进程即可。注意 pkill -x static-web-server 匹配不到截断名 static-web-serv，会误判「没有进程」。

Q3：systemctl start 后 is-active 显示 active 但 status 显示 Main process exited, code=exited, status=1/FAILURE？

说明进程启动后又退出了，Restart=always 正在反复拉起。看真实原因：journalctl -u static-web-server -n 30，常见两类——TLS 私钥 Permission denied (os error 13)（属主/权限问题，修法见安装指南 FAQ）与 TOML 反序列化失败（报错含具体键名，按提示修类型）。

Q4：generate 生成的补全不生效？

检查三步：文件已复制到 /etc/bash_completion.d/；已安装 bash-completion 包（apt-get install -y bash-completion）；新开 shell 或 source /etc/bash_completion.d/static-web-server.bash。zsh/fish/PowerShell 用户对应各自框架的加载方式（生成的 .zsh/.fish/.ps1 文件名在回显中已给出）。

Q5：如何确认优雅停机真的在工作？

方法一：grace-period 设为 2 后 time systemctl stop static-web-server，耗时约等于宽限期（实测 real 0m2.005s）；方法二：停机瞬间 journalctl -u static-web-server 应看到 grace period of 2s after the SIGTERM started → grace period has elapsed → delegating server's graceful shutdown 三连行。

Q6：哪里有完整参数清单可离线查阅？

static-web-server --help 输出即全量（含默认值与环境变量名）；或用 generate --man-pages 生成 man 页安装后 man static-web-server 离线阅读（4.5 节）。

七、参考链接

官方命令行参数文档：https://static-web-server.net/configuration/command-line-arguments/
环境变量说明：https://static-web-server.net/configuration/command-line-arguments/#environment-variables
systemd 部署参考（官方 unit 模板）：https://github.com/static-web-server/static-web-server/tree/master/systemd
v2.44.1 Release 页：https://github.com/static-web-server/static-web-server/releases/tag/v2.44.1
站内延伸阅读：《Static Web Server 介绍与选型指南》、《Ubuntu 22.04 安装 Static Web Server 指南》、《Static Web Server 2.44.1 配置参数详解》