update at 2026-02-10 14:30:30

apiserver/README.md

@@ -4,15 +4,41 @@
 - 小程序只上传参数（字体 ID、文字、字号、颜色等）
 - 服务端读取字体清单 + 字体目录，生成 SVG/PNG 后返回
 
-## 1. 启动
+## 1. 启动前准备（必须）
 
 在仓库根目录执行：
 
 ```bash
-python3 apiserver/server.py \
+cd /path/to/font2svg
+
+# 1) 创建并激活虚拟环境（launchd 默认使用这个解释器）
+python3 -m venv .venv
+source .venv/bin/activate
+
+# 2) 安装 Python 依赖
+python -m pip install -U pip
+python -m pip install -r requirements.txt
+
+# 3) 若需要 PNG 接口，再安装 Node 依赖
+npm install
+```
+
+快速验证：
+
+```bash
+/path/to/font2svg/.venv/bin/python -V
+/path/to/font2svg/.venv/bin/python -c "import fontTools, uharfbuzz; print('ok')"
+```
+
+## 2. 启动（前台调试）
+
+在仓库根目录执行：
+
+```bash
+/path/to/font2svg/.venv/bin/python apiserver/server.py \
   --host 0.0.0.0 \
   --port 9300 \
-  --static-root /home/gavin/font2svg
+  --static-root /path/to/font2svg
 ```
 
 其中 `--static-root` 目录必须包含：
@@ -22,7 +48,7 @@ python3 apiserver/server.py \
 
 如果不传 `--manifest`，默认优先读取 `<static-root>/miniprogram/assets/fonts.json`，不存在时回退到 `<static-root>/fonts.json`。
 
-## 2. API
+## 3. API
 
 ### GET `/healthz`
 
@@ -63,7 +89,7 @@ python3 apiserver/server.py \
 }
 ```
 
-## 3. Nginx 反向代理
+## 4. Nginx 反向代理
 
 在 `fonts.biboer.cn` 的 server 块中增加：
 
@@ -87,7 +113,7 @@ location /api/ {
 sudo nginx -t && sudo systemctl reload nginx
 ```
 
-## 4. systemd（Linux，可选）
+## 5. systemd（Linux，可选）
 
 仓库内提供示例：`apiserver/font2svg-api.service.example`，可复制到：
 
@@ -98,7 +124,7 @@ sudo systemctl enable --now font2svg-api
 sudo systemctl status font2svg-api
 ```
 
-## 5. launchd（macOS，可选）
+## 6. launchd（macOS，可选）
 
 仓库内提供示例：`apiserver/font2svg-api.launchd.plist.example`。
 
@@ -108,28 +134,45 @@ sudo systemctl status font2svg-api
 cp apiserver/font2svg-api.launchd.plist.example ~/Library/LaunchAgents/cn.biboer.font2svg-api.plist
 ```
 
-2. 加载并启动：
+2. 校验与权限修正：
 
 ```bash
+plutil -lint ~/Library/LaunchAgents/cn.biboer.font2svg-api.plist
+chown $(id -un):staff ~/Library/LaunchAgents/cn.biboer.font2svg-api.plist
+chmod 644 ~/Library/LaunchAgents/cn.biboer.font2svg-api.plist
+```
+
+3. 加载并启动（不要使用 `sudo`）：
+
+```bash
+launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/cn.biboer.font2svg-api.plist 2>/dev/null || true
 launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/cn.biboer.font2svg-api.plist
 launchctl enable gui/$(id -u)/cn.biboer.font2svg-api
 launchctl kickstart -k gui/$(id -u)/cn.biboer.font2svg-api
 ```
 
-3. 查看状态与日志：
+4. 查看状态与日志：
 
 ```bash
 launchctl print gui/$(id -u)/cn.biboer.font2svg-api
 tail -f /tmp/font2svg-api.log
 ```
 
-4. 停止并卸载：
+5. 停止并卸载：
 
 ```bash
 launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/cn.biboer.font2svg-api.plist
 ```
 
-## 6. 约束
+常见错误排查：
+
+- `Bootstrap failed: 5: Input/output error`
+  - 通常是 `plist` 路径/权限问题，或使用了 `sudo launchctl`。
+- `Missing executable detected`
+  - `plist` 中 `ProgramArguments` 第一个路径不可执行（常见是 `.venv` 未创建）。
+  - 先执行“启动前准备（必须）”创建 `.venv`，再重载 launchd。
+
+## 7. 约束
 
 - 字体解析完全基于字体清单（默认 `miniprogram/assets/fonts.json`），字体文件统一从 `<static-root>/fonts/` 读取，`fontId` 必须存在。
 - 服务端启用 CORS，允许小程序访问。