04 - 操作速查表

本指南将本地 AI 基础设施的日常操作整合为一份统一的参考手册。内容涵盖启动命令、服务器管理、API 密钥配置、维护计划及故障排除步骤，助您无需翻阅多份文档即可维持系统顺畅运行。

最实用的单一命令：

/Volumes/AI_DATA/Status-AI.command watch

保持终端标签页开启即可 — 每 5 秒自动刷新。

1. 运行 Status-AI.command — 找出哪个服务已停止。
2. Agent-server 停机 → Restart-Agent-Server.command。
3. Ollama 停机 → stop-ai-stack.command，然后 start-ai-stack.command。
4. 服务看似正常运行但请求失败 → Status-AI.command logs 查看报错。
5. 完全无法工作 → 检查 AI_DATA 卷是否已挂载。

一台服务器的密钥无法在另一台上通过验证。如果某个应用突然提示“API 密钥无效”，请检查其 URL 中是否遗漏了 :8443 端口号。

# 非流式模式
curl https://llmpowerhouses.taila4b91f.ts.net:8443/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" -H "Content-Type. application/json" \
  -d '{"model":"qwen3.6:35b-a3b","messages":[{"role":"user","content":"hello"}]}'

# 流式模式（-N 用于禁用 curl 的缓冲）
curl -N https://llmpowerhouses.taila4b91f.ts.net:8443/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" -H "Content-Type. application/json" \
  -d '{"model":"qwen3.6:35b-a3b","stream":true,"messages":[{"role":"user","content":"count to five"}]}'

# 列出模型及其实时驻留状态
curl https://llmpowerhouses.taila4b91f.ts.net:8443/v1/models -H "Authorization: Bearer YOUR_KEY"

所有端点（包括 /health）均需携带 Bearer 请求头 — 若直接请求返回 {"detail":"missing bearer token"} 属于正常行为，并非故障。

cd /Volumes/AI_DATA/apps/agent-server
venv/bin/python3 keys_admin.py list
venv/bin/python3 keys_admin.py create <app-name> --scope chat,tools --rate 60
venv/bin/python3 keys_admin.py rotate <key_id>
venv/bin/python3 keys_admin.py revoke <key_id>

--rate 为每分钟请求数。--daily-quota 为每日令牌配额（省略则代表无限制）。原始密钥仅打印一次——若丢失请执行轮换操作；它们无法被恢复。

ollama pull <model-name>
ollama rm <model-name>
ollama list

随之后更新三个位置，否则应用会提供不存在的模型：应用自身的模型表、SOP 的模型表以及 AGENT_SERVER_GUIDE_v2.md 中的每日日志。详细说明请参见 07_Switching_LLM_Models_Guide.md。无需重启代理服务器——/v1/models 会实时读取 Ollama 的数据。

1. 将文件拖入 knowledge-bank/DOD-FM-Knowledge-Bank/ 或 knowledge-bank/K12-Knowledge-Bank/（若不确定位置可先放入 _inbox/）。
2. 双击运行 Sync-Knowledge-Base.command。
3. 无需重启——索引会实时读取。移至 _archive/ 的文件将自动从搜索中撤出。 命名对检索至关重要： FMR-Vol03-Ch08_Unliquidated-Obligations_2025.pdf 的检索效果远优于 document (3).pdf。推荐格式：来源_主题_日期.扩展名。

每周（约 5 分钟）： 运行 Status-AI.command、Backup-AI.command，查看可用磁盘空间（低于 200 GB 需排查），检查 logs/agents/requests.jsonl 文件大小（超过约 500 MB 请压缩归档，切勿删除）。 每月（约 20 分钟）：

cd /Volumes/AI_DATA/apps/agent-server
venv/bin/python3 run_test_questions.py     # quality baseline
venv/bin/python3 build_eval_dashboard.py   # regenerate Eval-Dashboard.html
venv/bin/python3 keys_admin.py list        # revoke anything unused

• 不要删除 logs/agents/*.jsonl —— 这是仅有的延迟/质量历史记录。
• 不要删除 keys.db 或 memory.db —— 这两个都不可替换（密钥是哈希值且无法恢复；记忆只能从数周的真实使用中重建）。
• 不要运行 restart-ai-stack.command 期望重启代理服务器 —— 它只管理 Ollama、Open WebUI 和旧版网关。
• 不要在备份的情况下，编辑 apps/agent-server/ 下的任何文件。

cd /Volumes/AI_DATA/apps/llmpowerhouse-site
git pull

这是这个Mac上对于该文件夹唯一应该执行的git命令 —— 所有提交都在其他地方完成并推送到GitHub；Mac只是一个通过 git pull 刷新的只读镜像。千万不要在这里执行 git push、git add 或 git commit。 如果你看到 "branch and origin/main have diverged"（分支与原点main版本已分叉）：

git fetch origin
git reset --hard origin/main

这总是安全的 —— Mac端不应该有本地提交，而且被忽略的文件（gateway.env、api_keys.json、gateway.log）无论如何都不会受到影响。

• Start with Status-AI.command for any anomaly; it gives instant health, resident model status, and latency metrics.
• Never delete logs, keys, or memory databases; they are irreplaceable and contain hashed state that cannot be rebuilt from scratch.
• Agent-server restarts are lightweight; they only require Restart-Agent-Server.command and do not touch Ollama or the gateway.
• Naming conventions drive retrieval accuracy; use the Source_Topic_Date.ext pattern when dropshipping documents into the knowledge banks.
• Separate the two servers mentally; port 8443 serves the current infrastructure, while 8787/443 hosts legacy passthrough apps with distinct key spaces.