企业官网建设流程全解析

mlx-serve 是一个面向 Apple Silicon 的本地 LLM 推理服务器，纯 Zig 实现、无 Python 依赖，兼容 OpenAI 与 Anthropic API。本文带你完成生产部署的三件核心事：用--api-key给服务加一道访问门禁、把 Mac 变成常驻的无头推理节点、以及开启--metrics后如何接入 Prometheus 监控——最后附上一份可直接照抄的上线前观测清单。

一、无头模式启动：常驻 Mac 服务的一行命令

mlx-serve 的 CLI 从设计上就服务于脚本、launchd 和 headless Mac 场景（docs/cli.md）。默认监听--host 0.0.0.0 --port 11234，三种典型启动方式：

# 锁定单个模型常驻服务 mlx-serve --model ~/.mlx-serve/models/mlx-community/gemma-4-e4b-it-4bit --serve --port 11234 # 整个模型目录按名按需加载（与应用行为一致，生产多模型推荐） mlx-serve --serve --model-dir ~/.mlx-serve/models # GGUF 走同样的参数，自动路由到内置 llama.cpp mlx-serve --model ~/models/Qwen3.5-4B-Q4_K_M.gguf --serve

--model-dir可重复指定多个文件夹，服务端会维护 LRU 常驻集合、按名按需加载，非常适合多模型的生产部署。

二、api-key 门禁：保护网络暴露，不折腾本机

--api-key KEY的核心语义一句话：非 localhost 的请求必须携带密钥，localhost 保持开放。于是同一台机器上的应用和本地浏览器无需任何凭据，而密钥只负责保护--host 0.0.0.0带来的网络暴露。

客户端可选的密钥传递方式：

几个值得记住的设计细节：

• /health与 OPTIONS 请求永远开放，方便负载均衡与健康检查；
• 密钥比较使用常量时间比较，避免时序侧信道；
• 常见误区：因为 localhost 豁免，curl localhost不会看到 401——这是设计使然，验证门禁请用另一台机器的客户端；
• 远程客户端（持 api-key 或局域网共享）请求中的lora_paths等主机路径字段会直接 403，防止远程探测本机文件是否存在。

Claude Code、Codex 等 Agent CLI 通过 api-key 接入无头服务是最常见的生产用法；mlx-serve launch <agent>会自动写好对应配置，详见 docs/integrations.md。

三、常驻服务推荐配置（launchd 清单）

7×24 运行的服务，建议显式设置这些参数：

若还想让 Agent 在服务器上跑命令，macOS 内置的 Sandbox Terminal 会在隔离的 Linux 虚拟机中执行不可信命令，与常驻推理服务共存，是"让 Agent 放手干活"的稳妥姿势：

四、Prometheus 监控：开启 /metrics 与读法

启动时加上--metrics，即可零成本接入 Prometheus 生态——指标关闭时开销为零（每请求一次空指针检查，绝不在逐 token 路径上计时），因此生产环境可放心常开。实现是 src/metrics.zig 中的无锁计数器，写路径不阻塞解码线程。

数据入口有两个：

• GET /metrics—— 标准 Prometheus 文本格式，Prometheus 直接抓取
• GET /metrics.json—— 结构化 JSON，供内置 Web 控制台使用

指标名分两族：

• vllm:*—— 沿用 vLLM 标准命名，现有的 vLLM/Grafana 仪表盘可直接复用
• mlx_serve:*—— Apple 专属：GPU 利用率、进程内存、实时 tok/s、MLX 分配器细节

常用指标速查

三个容易踩的监控口径

1. prefill 速度要用"实际转发 token"做分子：用mlx_serve:prefill_tokens_total（剔除前缀缓存恢复部分）。若误用vllm:prompt_tokens_total，缓存命中时速度会被放大近 10 倍。不变式：prefill_tokens_total + prefix_cache_tokens_total == prompt_tokens_total。
2. 长 prefill 不代表卡死：mlx_serve:prefill_tokens_live与requests_prefilling暴露进行中的 prefill 实时进度，避免把分钟级 prefill 误报为挂死。
3. 谁在消耗你的 GPU 可见：/metrics.json的每个会话带request_id与client字段（claude-code / opencode / codex / omp / other）。

仓库自带监控回归：tests/test_metrics.sh 与 tests/test_metrics_outcomes.sh；想快速验证指标链路，浏览器打开/的内置控制台（Monitoring 面板）即可。

五、上线前安全检查与观测清单 ✅

值得放心的一点：mlx-serve 刻意不提供管理写接口（无 admin API）——监控面板只读，模型的加载/卸载走/v1/load-model、/v1/unload-model业务端点，同样受 api-key 保护。

相关资料

• CLI 与服务器参数：docs/cli.md · docs/zh-CN/cli.md
• API 参考（含/metrics、/metrics.json）：docs/api.md
• 架构与监控设计说明：docs/reference.md
• 指标实现：src/metrics.zig · 服务与鉴权：src/server.zig
• 局域网共享安全边界测试：tests/test_lan_share.sh