安装

Docker

发布出来的镜像是进来最短的一条路，文档其余部分也默认你走这条。

数据卷很重要。mcpd 会在 MCPD_DATA 指定的路径上写一个 SQLite 数据库，而没有数据卷的容器停止时会把你的 trace 一起带走。显式写明这个路径只多一个参数，却省掉了文件到底去了哪里这个问题。

每个参数都有对应的环境变量，所以命令行上能传的东西，用 -e 同样能设置。在任何你在意的地方，请固定一个标签，而不是跟着 latest 走。镜像为 linux/amd64 和 linux/arm64 两种平台构建，Docker 会拉取与你的机器相符的那一个。

Docker Compose

同一个容器，写成文件。当 mcpd 和你的应用同处一台主机时，用这种形式。

services:
  mcpd:
    image: ghcr.io/mcpd/mcpd:latest
    restart: unless-stopped
    ports:
      - "4317:4317"
    volumes:
      - mcpd-data:/data
    environment:
      MCPD_DATA: /data/mcpd.db
      MCPD_PROJECT: default
      # Set these before this port is reachable by anything but you.
      # MCPD_INGEST_KEYS: key-for-your-agents
      # MCPD_READ_KEYS: key-for-your-team
      # MCPD_RETENTION_DAYS: 30

volumes:
  mcpd-data:

注释掉的那三个键，要在这套东西接上别人也在的网络之前填好。一个密钥都不设置时，摄取和读取都是开放的，这在你自己的机器上是对的，在其他任何地方都是错的。部署讲了要设置什么，以及为什么。

Kubernetes

每次发布都会把 chart 以 OCI 制品的形式推送到与镜像相同的镜像仓库，所以不用先添加仓库。没有摄取密钥和读取密钥时，chart 会拒绝安装，所以请先生成这两个密钥。

mcpd 会处理 SIGTERM 并优雅退出，而这正是 Kubernetes 发出的信号。它用 /healthz 做存活探针，用 /readyz 做就绪探针，两者的区别是有意的：存活探针从不接触存储，所以一个慢的数据库不会把 Pod 送进重启循环。取值、探针和 Deployment 的形态在 Docker 与 Kubernetes 一页。

发布版二进制文件

每次发布都会附上 x86_64 和 arm64 Linux 的归档，以及 Apple 芯片和 Intel macOS 的归档。Linux 版是基于 musl 构建的静态二进制文件，所以不需要匹配 libc。随附一个 SHA256SUMS 文件和一份构建来源证明。解压与你的机器对应的归档，运行 ./mcpd；不带参数时，它会启动守护进程。

没有 cargo install mcpd。crates.io 上没有发布任何东西，而从注册表构建的 crate 也带不上界面，因为界面是用 npm 构建、再编译进二进制文件的。如果你有 Rust 工具链，请改为从源码构建。

从源码构建

克隆仓库，运行发行版构建。它使用完整的链接时优化和单个代码生成单元，编译更慢，但产出的二进制文件更小也更快。请走 make，不要直接用 cargo：界面是编译进二进制文件里的，make dist 会先把界面构建出来，而在一份全新克隆上直接 cargo build 没有办法做这一步。这一步除了 Rust 工具链，还需要机器上有 Node 和 npm。

二进制文件写在 target/dist/mcpd，走更快那条路的话则是 target/release/mcpd。开发 mcpd 本身时用 make build，要拿去运行的东西用 make dist。

数据放在哪里

--data 是 SQLite 文件的路径，默认是工作目录下的 ./mcpd.db。上级目录会自动为你创建。

传入 :memory: 会把一切留在内存里，不往磁盘写任何东西。测试套件、在别人机器上的演示，以及任何你不愿留下提示词的运行，都该选它。存储随进程一起消失，这正是它的用意。

mcpd demo 会往存储里填入一次逼真的失败运行，然后开始服务，这样你第一次打开界面时里面就有东西可看。

启动之前先看它会做什么

mcpd config 会打印这次调用最终解析出的配置，然后退出。参数、环境变量和默认值都落在同一份清单里，你不用启动任何东西就能看出是哪一个生效了。

$ mcpd configlisten          0.0.0.0:4317storage         sqlite at ./mcpd.dbconfig file     nonelog format      textproject         defaultprojects        noneretention       foreveringest auth     openread auth       openwrite auth      openadmin auth      openexecute auth    openworker auth     opensignup          offruns            sqlite at ./mcpd.runs.dbrun settings    lease_ttl_ms 30000, reclaim_window_ms 30000, stall_window_ms 300000, idempotency_window_ms 86400000, park_ttl_ms 86400000, max_depth 8, max_step_repeats 16identity        offclient ip       peer addresssampling        keep everythingquota           unlimitedredaction       onredact key      built in, which is public; set --redact-keycors            same-origin onlytimeout         30s per requestlimits          32 MiB per request, 10000 signals per batchderived         duration and token metricsaspects         offmonitors        noneobjectives      nonejudge           offforwarding      off

验证安装

/healthz 回答的是它到底跑起来了没有。它从不读存储，所以既快，也只如实反映进程本身，而不是磁盘。

$ curl -s localhost:4317/healthz{"status":"ok","version":"0.1.0","spec_version":"1.0.0","uptime_seconds":8,"storage":"sqlite"}$ curl -s -o /dev/null -w "%{http_code}\n" localhost:4317/readyz200

spec_version 是这个构建实现的数据模型版本。客户端可以读它，然后拒绝与自己不理解的服务器通信，这好过发出一个会被逐个字段拒绝的批次。

/readyz 是另一半。它会探一下存储，存储不可达时回答 503，这样负载均衡器就不再把读请求发给一个服务不了它们的实例。存活探针用 /healthz，就绪探针用 /readyz，绝不要两处用同一个。

然后打开 localhost:4317，你看到的就是界面。

接下来

• 从你自己的智能体给它发一条 trace：快速开始。
• 认识文档其余部分要用到的词：概念。
• 每一个参数和环境变量汇成一张表：配置。
• 在别人能访问到这个端口之前：Docker 与 Kubernetes。