MyCodex

MyCodex Relay 0.1.0

使用 Docker Compose 部署 Relay

适用于单实例生产部署。镜像支持 linux/amd64 与 linux/arm64， 默认只把明文服务发布到宿主机回环地址，由 Nginx、Caddy 或 Traefik 提供公网 HTTPS。

当前发布状态

Docker 部署包已经构建并通过双架构验收，GitCode 公开附件尚未上传。以下命令在附件发布后可直接使用。

部署结构

Relay 容器以固定的非 root 用户 10001:10001 运行。根文件系统只读，只有状态卷和/tmp 可写。

1. 下载并加载镜像

在 Docker 主机上将架构改为 linux-amd64 或 linux-arm64：

VERSION=0.1.0
ARCH=linux-arm64
PACKAGE="mycodex-relay-${VERSION}-docker-${ARCH}.tar.gz"
BASE="https://api.gitcode.com/api/v5/repos/gcw_SpGZ48lW/mycodex-updates/releases/relay-v${VERSION}/attach_files"

curl -fL "$BASE/$PACKAGE/download" -o "$PACKAGE"
curl -fL "$BASE/DOCKER-SHA256SUMS.txt/download" -o DOCKER-SHA256SUMS.txt
grep "  $PACKAGE\$" DOCKER-SHA256SUMS.txt | sha256sum -c -
tar -xzf "$PACKAGE"
cd "${PACKAGE%.tar.gz}"
docker load -i mycodex-relay-image.tar

包内的 .env 已将 Compose 镜像版本锁定为下载版本。

2. 准备配置

cp docker/relay-config.example.json docker/relay-config.json

编辑 docker/relay-config.json，重点确认：

  • listenHost 保持 0.0.0.0，端口保持 38443。
  • publicHost 设置为 Relay 的公网域名。
  • 外部反向代理提供 HTTPS 时，设置 publicPort: 443 和 publicTls: true。
  • statePath 保持 /var/lib/mycodex-relay/relay-state.db。
  • 由反向代理终止 TLS 时，保持内置 tls.enabled: false。
不要提交部署配置

docker/relay-config.json 可能包含部署信息，应留在服务器并限制读取权限。

3. 创建首个租户并启动

docker compose run --rm relay local ensure-tenant \
  --config /etc/mycodex-relay/relay-config.json \
  --name Production \
  --json

输出中的 secret.value 只显示一次。立即保存到密码管理器，不要写入仓库或日志。

docker compose up -d --no-build
docker compose ps
curl http://127.0.0.1:38443/health

4. 配置反向代理

以下 Nginx 片段保留 WebSocket Upgrade，并只向本机 Relay 转发：

location / {
    proxy_pass http://127.0.0.1:38443;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 180s;
    proxy_send_timeout 180s;
    proxy_buffering off;
}

不要把 Compose 端口映射改成无主机地址的 38443:38443，否则明文端口会绑定所有宿主机接口。

5. 备份与升级

命名卷保存数据库、Relay 身份私钥和迁移备份，必须作为一个整体保留：

docker compose stop relay
mkdir -p backup
cp docker/relay-config.json backup/relay-config.json
docker run --rm \
  -v mycodex-relay_relay-data:/data:ro \
  -v "$PWD/backup:/backup" \
  alpine:3.23 \
  tar -C /data -czf /backup/relay-data.tar.gz .
docker compose start relay

加载新版本镜像后运行：

docker compose up -d --no-build
curl http://127.0.0.1:38443/health
不要执行 docker compose down -v

-v 会删除包含数据库与 Relay 身份私钥的命名卷。