词驿 WordRelay

主题

部署 ​

本页带你在一台全新的 Linux 服务器上把词驿 WordRelay 私有化部署跑起来：从准备环境、启动引擎与控制台，到验证服务健康。全部示例基于 Docker（推荐）；裸机二进制部署见本页末尾。

整个流程通常不超过 15 分钟。部署完成后的初始化（创建管理员、接入渠道、签发令牌）请继续看下一页：初始化。

1. 前置要求 ​

项要求
操作系统任意能运行 Docker 的 Linux（x86_64 / arm64）
Docker20.10+（含 docker CLI）
内存1 GB 起步（引擎为 Go 单二进制 + SQLite，无外部数据库依赖）
磁盘引擎镜像约 30 MB；数据只增不删，按调用量预留（日志与流水是大头）
端口引擎默认监听 6200，控制台默认 8081；对外可用 nginx 收敛（见运维）

为什么没有数据库依赖

词驿引擎使用嵌入式 SQLite（纯 Go 驱动），全部状态落在一个数据文件里。你不需要安装 MySQL/PostgreSQL，也没有连接池、账号密码要管理；备份就是备份这一个文件（加 WAL 文件）。

2. 获取镜像 ​

两种方式任选：

方式 A：使用交付的镜像包（私有化交付常见形态）

bash
# 加载交付包里的两个镜像
docker load -i ciyi-core.tar.gz
docker load -i ciyi-web.tar.gz

方式 B：从源码构建（你有源码访问权时）

bash
git clone <你的交付仓库地址> wordrelay
cd wordrelay

# 引擎镜像（纯 Go、无 CGO 静态编译）
docker build -f core/deploy/Dockerfile -t ciyi-core:latest ./core

# 控制台镜像（React 静态资源 + nginx）
docker build -f web/deploy/Dockerfile -t ciyi-web:latest ./web

构建产物：

  • ciyi-core —— 引擎（ciyid），API 网关本体 + 管理面 API，默认监听 6200
  • ciyi-web —— 管理控制台（静态站 + 同源反代），默认 8081 → 80

3. 准备环境变量 ​

引擎只硬性要求一个环境变量：

CIYI_CREDENTIAL_KEY（必填） ​

渠道凭证的 AES-GCM 加密密钥。所有上游 API Key 都以密文形态入库——数据库文件泄露时不直接泄露上游凭证。

bash
# 生成一份（base64 单行输出）；只此一份，务必保存到密码管理器
docker run --rm ciyi-core:latest /usr/local/bin/ciyictl genkey

密钥丢失 = 密文不可恢复

CIYI_CREDENTIAL_KEY 丢失后，已入库的渠道凭证与令牌明文无法解密，只能逐个重新录入。请把它当作最高等级的机密对待：生成一次、妥善保存、部署时经环境变量注入（不要写进任何文件或 git）。

CIYI_SETUP_CODE（可选——激活码） ​

初始化引导页的激活码门槛。这是商业化授权的接入端口：

  • 不设置：引导页无激活码步骤，首次访问直接设置管理员账户（自部署场景最简形态）
  • 设置：引导页第一步要求输入与该值一致的激活码，错误 5 次锁定 5 分钟

交付型部署通常设置它，由交付方在部署时注入、并告知最终客户。

CIYI_ADMIN_PASSWORD（可选——跳过引导页） ​

脚本化部署可以不经引导页，直接用环境变量 seed 首个管理员：

  • 首次启动时自动创建用户名为 admin 的管理员（密码为该值，bcrypt 入库）
  • 已有管理员后该值不再生效（修改密码走控制台）

它与引导页互斥幂等：env seed 先行则引导页不再出现；两者都不提供，则首次访问控制台会进入初始化引导页。

4. 启动容器 ​

bash
# 数据目录（SQLite 数据文件落这里；后续备份/升级都以它为准）
sudo mkdir -p /opt/ciyi-core/data

# 引擎
docker run -d --name ciyi-core \
  --restart unless-stopped \
  -p 6200:6200 \
  -v /opt/ciyi-core/data:/var/lib/ciyi \
  -e CIYI_CREDENTIAL_KEY=<genkey 输出的那串 base64> \
  [-e CIYI_SETUP_CODE=<交付方提供的激活码>] \
  ciyi-core:latest

# 控制台（无状态、无敏感 env；经 docker 网络反代引擎 API）
docker network create ciyi-net 2>/dev/null || true
docker network connect ciyi-net ciyi-core

docker run -d --name ciyi-web \
  --restart unless-stopped \
  --network ciyi-net \
  -p 8081:80 \
  ciyi-web:latest

要点：

  • 数据卷必须挂：不挂 /var/lib/ciyi，容器重建即丢库（SQLite 文件在容器层）。
  • 首次启动自动建表：空数据目录启动时会自动执行全部数据库迁移，不需要任何手工建库步骤；迁移进度记录在库内，重启幂等。
  • 引擎与控制台放同一 docker 网络，控制台 nginx 用服务名 ciyi-core:6200 反代 /api/。
  • CIYI_CREDENTIAL_KEY 只经 -e 注入，不落盘。更换机器迁移时带上同一密钥，密文数据才能继续解密。

5. 验证部署 ​

三步验证，全部通过即部署完成：

bash
# 1) 引擎健康检查（本机）
curl http://127.0.0.1:6200/healthz
# 预期输出：ok

# 2) 初始化状态（首次部署应为 true——引导窗口开着）
curl http://127.0.0.1:8081/api/v1/setup/status
# 预期输出：{"needs_setup":true,"code_required":false}

# 3) 控制台页面
curl -I http://127.0.0.1:8081/
# 预期：HTTP/1.1 200

看到 needs_setup:true 就说明一切就绪——打开浏览器访问 http://<服务器地址>:8081，会被自动带入初始化引导页。

6. 裸机二进制部署（可选） ​

不使用 Docker 时，make build（或交叉编译 CGO_ENABLED=0 go build）产出两个二进制：

bash
bin/ciyid -config /etc/ciyi/config.yaml    # 引擎（config.yaml 可不存在，全字段有默认值）

控制台则需要任一静态服务器托管 web/dist/，并把 /api/ 反代到引擎 :6200（参考 web/deploy/nginx.conf）。env 变量与数据持久化要求与容器部署完全一致（数据文件默认 ciyi.db，路径由 config.yaml 的 database.dsn 决定）。

7. 常见部署问题排查 ​

端口被占用

docker: Error response from daemon: port is already allocated —— 换一个宿主端口（如 -p 16200:6200），控制台镜像构建时通过 CORE_UPSTREAM 模板变量指向新地址；或停掉占用端口的进程。

引擎启动即退出，日志提示 credential key 无效

CIYI_CREDENTIAL_KEY 未设置或不是合法 base64 时引擎拒绝启动（fail-closed）。重新用 genkey 生成并完整复制（单行、含可能的 = 结尾）。

healthz 通，但控制台打不开

两容器不在同一 docker 网络（控制台 nginx 解析不了 ciyi-core 主机名）：docker network connect ciyi-net ciyi-core 后重启 ciyi-web。

数据目录权限

容器内以非 root 运行时，确保宿主目录对容器用户可写：sudo chown -R 65532:65532 /opt/ciyi-core/data（按镜像实际 UID 调整；root 运行则无此问题）。

下一步

部署完成 → 初始化：设置管理员、接入第一个上游渠道、签发第一个令牌、发出第一个请求。

© 2026 词驿 WordRelay