Docker Compose 部署

准备 compose 文件

# docker-compose.yml
services:
  meta-gateway:
    image: zichuanlan/meta-gateway:${IMAGE_TAG:-latest}
    container_name: meta-gateway
    restart: unless-stopped
    ports:
      - "4100:4100"
    volumes:
      - ./data:/data
    environment:
      ADMIN_TOKEN: ${ADMIN_TOKEN:?ADMIN_TOKEN required}
      MASTER_KEY: ${MASTER_KEY:?MASTER_KEY 32-char required}
      METRICS_TOKEN: ${METRICS_TOKEN:-mg-metrics-secret}

IMAGE_TAG 默认 latest，也就是当前正式版（v4.0.0）；预发布用 beta。

生成密钥并启动

export ADMIN_TOKEN=$(openssl rand -hex 16)
export MASTER_KEY=$(openssl rand -hex 16)   # 32 字符加密主密钥
docker compose up -d

启动后访问 http://localhost:4100/console/，输入 ADMIN_TOKEN 进入控制台。

单行 docker run

docker run -d --name meta-gateway \
  -p 4100:4100 \
  -e ADMIN_TOKEN=your-secure-admin-token \
  -e MASTER_KEY=your-32-char-encryption-key-here!! \
  -e SELFUPDATE_TRACK_TAG=latest \
  -v ./data:/data \
  --restart unless-stopped \
  zichuanlan/meta-gateway:latest

NOTE

SELFUPDATE_TRACK_TAG 是你要跟踪的镜像标签（这里 = latest 正式版，预发布用 beta）。 它有两个作用： 控制台的更新弹窗会按它显示“当前跟随哪个渠道”，而且网关靠它判断“这个容器的环境变量是不是它本来该有的”。 用 docker run 部署时它不会自动存在，建议带上；否则控制台会误以为你还没应用部署文件而弹一次提示 （提示可以“稍后”关掉，不影响使用）。

三个必填项

变量	作用	注意
ADMIN_TOKEN	控制台管理员登录口令	不是 METRICS_TOKEN；两者不要复用
MASTER_KEY	凭证库 AES-GCM 主密钥	必须 ≥ 32 字符；丢了就再也解不开已存的凭据与 cookie
METRICS_TOKEN	Prometheus /metrics 抓取凭据	可留空，但留空后 /metrics 需要 TRUSTED_SCRAPER_CIDRS 才可访问

IMPORTANT

MASTER_KEY 必须随数据库一起备份、一起迁移。 换一个 MASTER_KEY 启动同一个库，所有 secret_enc / cookie_enc / token_enc 字段都无法解密。恢复备份时这条是第一位。

容器运行身份与数据卷

镜像以 UID/GID 10001 运行，数据库与备份都在 /data。

• 新建的命名卷会自动继承正确属主，无需干预。
• 升级已有的 bind mount 或旧卷之前，先停服务，再把数据目录改成 UID/GID 10001 可写，否则容器起不来。

健康检查

curl --fail http://127.0.0.1:4100/readyz

/readyz 在排空（draining）或 SQLite 不可达时返回 503。/healthz 只是进程存活检查。

下一步

• 源码构建运行
• 升级与更新渠道 —— 正式版与预发布的区别，以及从 v3 升级与换渠道怎么操作
• 基础 URL 与端点规则 —— 开始接上游
• 配置全表 —— 所有环境变量