生产部署

架构概览

生产环境把固定基础设施、Web release 和 Worker release 分开管理。公网 Compose 可以由 Traefik 自动申请 Let's Encrypt TLS 证书；当前日常发布不会把 Web 与长任务 Worker 一起重启：

Internet
  └─→ Traefik（memex-server 基础设施 project）
        ├─→ active memex-web-<release>（Web UI + HTTP API）
        └─→ memex-mcp

PostgreSQL / Redis（memex-server 基础设施 project）
  └─→ active memex-worker-<release>（scheduler / runner / Butler）
        └─→ retiring Worker generations（仅完成已有长任务）

配置步骤

1. 填写环境变量

cp .env.example .env

编辑 .env，填写以下必填项：

变量	说明
ENGINE_DIR	Memex 引擎目录（只读挂载）
MEMEX_HOST	对外域名，如 memex-server.memect.cn
ACME_EMAIL	Let's Encrypt 注册邮箱

2. 启动

docker compose --env-file .env up -d

Traefik 会自动申请证书，首次启动稍等片刻。

3. 创建管理员 Token

curl -X POST https://memex-server.memect.cn/api/v1/auth/tokens \
  -H "Content-Type: application/json" \
  -d '{"name":"admin","username":"admin","role":"admin"}'

危险

生产镜像默认以 --auth 启动，滚动 Web overlay 也显式启用认证。修改启动命令时不得移除 --auth；否则所有请求会获得 admin 权限。

日常滚动发布

首次启动只是 bootstrap。当前托管生产使用 .env.local 与固定 memex-server 基础设施 project，后续通过同一入口分别发布 Web 和 Worker：

# API / GUI：readiness 后切 Traefik，不改变 Worker admission
bash scripts/deploy.sh --build --web-only

# scheduler / runner / Butler / Engine：不构建文档、不切 Traefik
bash scripts/deploy.sh --build --worker-only

# 同一提交同时修改两者：默认先 Worker、后 Web
bash scripts/deploy.sh --build

Worker 先以 standby 上报 heartbeat，激活后才领取新任务。旧 Worker 不做全局 drain，也不会 被直接重启；已有 runner 在 checkpoint、durable loop progress 或 Butler round 边界持久化 continuation 后退出。持久 retirement monitor 等待 lease、Butler generation 和执行进程全部 归零后再停止旧容器。

因此发布状态必须分开记录：active 表示新 generation 已接管流量或任务准入，converged 表示旧 generation 已完全退出。回滚也应从上一个已验证 commit 重新发布不可变 image/Engine worktree，不能切换共享 Engine symlink。详细检查项见仓库内 docs/service/DEPLOY.md。

环境变量完整参考

变量	必填	默认值	说明
ENGINE_DIR	✓	—	宿主机 Engine Git checkout；发布时固定为 generation worktree
DATABASE_URL	✓	—	PostgreSQL 连接串；生产不允许 SQLite 回退
REDIS_URL	✓	—	Redis 连接串，用于跨进程 lease 与运行协调
MEMEX_WIKIS_DIR		~/wikis	wiki 产出目录
MEMEX_LOG_RETAIN_DAYS		30	日志保留天数
MEMEX_MAX_CONCURRENT_JOBS		3	非峰时系统作业并发硬上限
MEMEX_PEAK_HOURS_ENABLED		0	是否启用峰时容量折减
MEMEX_PEAK_HOURS_RATIO		0.6	峰时相对硬上限的并发比例；峰谷关闭时不生效
MEMEX_RECONCILER_INTERVAL		30	孤儿、超时与配置漂移对账周期（秒）
MEMEX_HARNESS_RUNTIME_DIR_HOST		/data/memex/harness-runtime	Harness RFC、lessons 与监工运行产物目录
MEMEX_CORS_ORIGINS		关闭	CORS 白名单，逗号分隔
FASTMCP_HOST		0.0.0.0	MCP 服务监听地址
FASTMCP_PORT		9001	MCP 服务监听端口

数据持久化

平台权威状态存储在 PostgreSQL；Redis 使用持久卷保存 AOF/RDB，但 lease 仍应视为可重建的 运行协调状态。Wiki Git repo、.uploads/、日志与 Harness 可写运行产物都应挂载到宿主机持久 目录。备份必须覆盖 PostgreSQL、Wiki Git/上传资产和必要的 Redis 持久数据，而不是备份某个 Web/Worker 容器。