跳转至

文档站点运维

最后更新：2026-07-24。

本页负责 MkDocs build、localhost 静态服务与 Tailscale Funnel 的部署、更新、回滚和诊断。它记录主机操作，不属于研究证据。

当前拓扑

docs/**/*.md
  → .venv-docs/bin/python -m mkdocs build --strict
  → site/
  → http://127.0.0.1:8000
  → Tailscale Funnel HTTPS
  → https://user-hp-z8-g4.tail5b1fcb.ts.net/

已验证（2026-07-24）：当前站点通过 Funnel 对公网开放；HTTPS 请求返回 200 text/html。公开范围是完整 site/，不是脱敏副本。

安装

文档环境与 simulator/PyTorch 环境隔离：

python -m venv .venv-docs
.venv-docs/bin/python -m pip install -r requirements-docs.txt

requirements-docs.txt 固定 mkdocs==1.6.1 和 mkdocs-material==9.7.7。.venv-docs/ 与生成的 site/ 均由 .gitignore 排除。

本地开发

.venv-docs/bin/python -m mkdocs serve --dev-addr 127.0.0.1:8000

开发 server 只监听 localhost。它用于编辑预览，不作为正式静态服务。

正式 build

.venv-docs/bin/python -m mkdocs build --strict

任何导航、内部链接、配置或 Markdown warning 都应先修复。不得手工修改 site/ HTML。

静态服务

build 成功后：

.venv-docs/bin/python -m http.server 8000 \
  --bind 127.0.0.1 \
  --directory site

正式服务由用户级 physhsi-docs.service 托管：

systemctl --user status physhsi-docs.service
systemctl --user restart physhsi-docs.service

unit 位于 ~/.config/systemd/user/physhsi-docs.service，已加入 default.target。它只监听 127.0.0.1:8000，不直接向 LAN 或公网开放端口。

Tailscale

当前主机状态

主机账号无系统 sudo 权限，因此本次使用 Tailscale 官方校验过的 static binary 1.98.9：

.local-tools/tailscale_1.98.9_amd64/

state/socket 位于被忽略的 .tailscale/。用户态 daemon 启动命令：

.local-tools/tailscale_1.98.9_amd64/tailscaled \
  --tun=userspace-networking \
  --state=/mnt/data/PhysHSI/.tailscale/tailscaled.state \
  --statedir=/mnt/data/PhysHSI/.tailscale \
  --socket=/mnt/data/PhysHSI/.tailscale/tailscaled.sock

正式 daemon 由用户级 physhsi-tailscaled.service 托管：

systemctl --user status physhsi-tailscaled.service
systemctl --user restart physhsi-tailscaled.service

unit 位于 ~/.config/systemd/user/physhsi-tailscaled.service，已加入 default.target。--statedir 是证书签发和缓存所必需；缺失时 Funnel TLS 会报 no TailscaleVarRoot。

CLI 前缀：

.local-tools/tailscale_1.98.9_amd64/tailscale \
  --socket=/mnt/data/PhysHSI/.tailscale/tailscaled.sock

先核对本机 CLI

每次重配前运行：

<tailscale-cli> funnel --help
<tailscale-cli> funnel status

本机 1.98.9 的准确语法是：

<tailscale-cli> funnel --bg --yes http://127.0.0.1:8000

检查：

<tailscale-cli> funnel status
curl -I https://user-hp-z8-g4.tail5b1fcb.ts.net/

系统管理员若以后完成 apt/systemd 安装，可把 <tailscale-cli> 换成 tailscale，其余先以该版本的 funnel --help 为准。

更新

  1. 修改 docs/**/*.md 或 CSS。
  2. 运行 strict build。
  3. 本地检查首页、导航、light/dark/mobile。
  4. 现有静态 server 会直接读取新 site/；无需重配 Funnel。
  5. 再次访问公网 HTTPS 地址确认。

回滚

文档 source 才是唯一内容源：

  1. 在 Git 中恢复目标 docs revision；不要编辑 site/。
  2. 重新运行 mkdocs build --strict。
  3. 保持 localhost server 与 Funnel 配置不变。

仅停止当前 HTTPS proxy：

<tailscale-cli> funnel --https=443 off

funnel reset 会清除该 node 的全部 Funnel 配置；只有确认没有其它共享服务时才使用。关闭 Funnel 后，完整文档将不再从公网访问。

诊断

现象 检查
localhost 不通 ss -ltnp 'sport = :8000'，确认 build 与 server
Funnel 无配置 <tailscale-cli> funnel status
HTTPS 域名错误 tailscale status --json 的 Self.DNSName 与 CertDomains
TLS internal error 检查 daemon 是否带 --statedir，并查看 journalctl --user -u physhsi-tailscaled.service
页面是旧版 strict rebuild，确认 server 的 --directory site
daemon 重启后离线 确认两个 user service 均为 enabled 和 active

用户会话边界

两个 unit 已启用用户级启动，但当前 loginctl show-user yehang 显示 Linger=no。因此它们会随用户 manager 启动；若要求无人登录时也从开机持续运行，需要另行授权并执行 loginctl enable-linger yehang。