作者:
    Creation:2026-06-30Last update:2026-06-30

    自托管 Intlayer

    Intlayer 可以完全在您自己的基础设施上运行——无需 Intlayer Cloud 账户。只需一条命令即可启动一个生产就绪的堆栈：

    sh
    curl -fsSL https://intlayer.org/install.sh | sh

    安装程序会下载 docker-compose.yml 和 .env 文件，自动生成所需的密钥，并使用 docker compose up -d 启动所有容器。

    目录

    架构

    plaintext
                    ┌─────────────────────────────┐ browser ──────▶ │  app  (TanStack Start)  :3000│ ──┐                └─────────────────────────────┘   │ VITE_BACKEND_URL                ┌─────────────────────────────┐   │                │  backend (Fastify/Bun)  :3100│ ◀─┘                └──────────────┬──────────────┘          ┌──────────┬─────────┼──────────┬───────────┐          ▼          ▼         ▼          ▼           ▼     mongo:27017  redis:6379  minio:9000  mailpit:1025  Chromium     (1-node RS)             (S3 API)     (SMTP)        (in-image)                             minio:9001   mailpit:8025                             (console)    (web UI)

    Chromium（用于 Puppeteer 屏幕截图生成）捆绑在后端镜像中——无需单独的容器。

    先决条件

    • Docker ≥ 24 和 Docker Compose ≥ v2。如果其中任何一个缺失，安装程序将打印安装链接并退出。
    • 主机上端口 3000、3100、8025、9000 和 9001 可用。
    • Linux 或 macOS 主机（或 Windows 上的 WSL2）。

    快速开始

    sh
    curl -fsSL https://intlayer.org/install.sh | sh

    安装程序执行以下操作：

    1. 检查 docker 和 docker compose 是否存在。
    2. 将 docker-compose.yml 和 .env.example 下载到 ./intlayer/ 目录中。
    3. 如果不存在 .env 文件，则复制示例文件并使用 openssl rand 为 BETTER_AUTH_SECRET、S3_ACCESS_KEY_ID 和 S3_SECRET_ACCESS_KEY 生成随机密钥。
    4. 运行 docker compose pull + docker compose up -d。
    5. 打印 URL：仪表盘 :3000、API :3100、电子邮件 UI :8025、MinIO 控制台 :9001。

    堆栈启动后，打开 http://localhost:3000 并创建您的第一个账户。

    服务

    服务 镜像 主机端口 用途
    app 从 apps/app/Dockerfile 构建 3000 TanStack Start 仪表盘 (CMS UI)
    backend 从 apps/backend/Dockerfile 构建 3100 Fastify REST API (/health 端点)
    mongo mongo:7 内部 单节点副本集 (rs0)
    redis redis:7-alpine 内部 任务队列 (BullMQ) 和缓存 (ioredis)
    minio minio/minio 9000 (S3), 9001 (控制台) 用于头像和截图的 S3 兼容对象存储
    mailpit axllent/mailpit 1025 (SMTP), 8025 (Web UI) 本地事务性电子邮件接收器

    默认情况下，内部端口（mongo、redis）不会暴露给主机。

    MinIO 端口 9000 必须可从浏览器访问，因为上传的资产（头像、截图）直接从 S3_PUBLIC_URL=http://localhost:9000/intlayer 加载。

    环境变量

    安装程序会生成一个即用型 .env 文件。下表描述了每个变量。

    必需（自动生成或提示）

    变量 示例 描述
    NODE_ENV production 运行时环境
    PORT 3100 后端监听端口
    BACKEND_URL http://localhost:3100 后端 API 的公共 URL
    APP_URL http://localhost:3000 仪表盘的公共 URL
    DOMAIN localhost Cookie 域
    MONGODB_URI mongodb://mongo:27017/intlayer?replicaSet=rs0 完整的 MongoDB 连接 URI
    REDIS_URL redis://redis:6379 Redis 连接 URL
    BETTER_AUTH_SECRET (已生成) 用于会话签名的 32 字节密钥
    MAIL_PROVIDER smtp 邮件传输方式：smtp 或 resend
    MAIL_SMTP_HOST mailpit SMTP 主机名 (Mailpit 容器名称)
    MAIL_SMTP_PORT 1025 SMTP 端口
    MAIL_FROM Intlayer <no-reply@localhost> 发件人地址
    S3_ENDPOINT http://minio:9000 S3 兼容端点
    S3_PUBLIC_URL http://localhost:9000/intlayer 用于浏览器资产加载的公共 URL
    S3_BUCKET_NAME intlayer 存储桶名称
    S3_ACCESS_KEY_ID (已生成) MinIO 访问密钥
    S3_SECRET_ACCESS_KEY (已生成) MinIO 秘密密钥
    VITE_BACKEND_URL http://localhost:3100 构建时嵌入到仪表盘中的后端 URL
    VITE_DOMAIN localhost 构建时嵌入到仪表盘中的域

    可选（缺少时功能会优雅降级）

    变量 功能
    OPENAI_API_KEY AI 辅助翻译和内容审计
    STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_* 账单和订阅管理
    RESEND_API_KEY 通过 Resend 发送事务性电子邮件（设置后会覆盖 Mailpit）
    GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET GitHub OAuth 登录
    GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET Google OAuth 登录
    GITLAB_CLIENT_ID, GITLAB_CLIENT_SECRET GitLab OAuth 登录
    MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET Microsoft OAuth 登录
    LINKEDIN_CLIENT_ID, LINKEDIN_CLIENT_SECRET LinkedIn OAuth 登录
    ATLASSIAN_CLIENT_ID, ATLASSIAN_CLIENT_SECRET Atlassian OAuth 登录

    连接您的 Intlayer 项目

    堆栈运行后，将您的项目指向自托管的后端和仪表盘，而不是 intlayer.org。

    项目配置

    intlayer.config.ts
    import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  editor: {
    clientId: process.env.INTLAYER_CLIENT_ID,
    clientSecret: process.env.INTLAYER_CLIENT_SECRET,

    /**
     * 自托管 CMS 仪表盘的 URL。
     * 默认值: https://app.intlayer.org
     */
    cmsURL: process.env.INTLAYER_CMS_URL, // e.g. http://localhost:3000

    /**
     * 自托管后端 API 的 URL。
     * 默认值: https://back.intlayer.org
     */
    backendURL: process.env.INTLAYER_BACKEND_URL, // e.g. http://localhost:3100
  },
};

export default config;

    在您项目的 .env 中设置环境变量：

    sh
    INTLAYER_CMS_URL=http://localhost:3000INTLAYER_BACKEND_URL=http://localhost:3100INTLAYER_CLIENT_ID=<your-client-id>INTLAYER_CLIENT_SECRET=<your-client-secret>

    在您的自托管仪表盘中，通过 http://localhost:3000/projects 下的 项目 → 访问密钥 创建访问凭据。

    @intlayer/api SDK

    以编程方式使用 @intlayer/api SDK 时，明确传递 backendURL：

    cms.ts
    import { createIntlayerCMS } from "@intlayer/api";import { dictionaryEndpoint } from "@intlayer/api/dictionary";const cms = createIntlayerCMS({  editor: {    clientId: process.env.INTLAYER_CLIENT_ID,    clientSecret: process.env.INTLAYER_CLIENT_SECRET,    backendURL: process.env.INTLAYER_BACKEND_URL, // http://localhost:3100  },});const { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();

    升级

    在现有部署上重新运行安装程序会执行滚动升级：

    sh
    curl -fsSL https://intlayer.org/install.sh | sh

    这会拉取最新镜像并使用 docker compose pull && docker compose up -d 重启容器。现有卷（mongo-data、redis-data、minio-data）会保留——不会丢失数据。

    要在 ./intlayer/ 目录中手动升级：

    sh
    docker compose pulldocker compose up -d

    备份与恢复

    所有持久化数据都存储在三个命名 Docker 卷中。

    备份

    sh
    docker run --rm \  -v intlayer_mongo-data:/data \  -v "$(pwd)":/backup \  busybox tar czf /backup/mongo-data.tar.gz /datadocker run --rm \  -v intlayer_redis-data:/data \  -v "$(pwd)":/backup \  busybox tar czf /backup/redis-data.tar.gz /datadocker run --rm \  -v intlayer_minio-data:/data \  -v "$(pwd)":/backup \  busybox tar czf /backup/minio-data.tar.gz /data

    恢复

    sh
    docker run --rm \  -v intlayer_mongo-data:/data \  -v "$(pwd)":/backup \  busybox tar xzf /backup/mongo-data.tar.gz -C /# 对 redis-data 和 minio-data 重复此操作

    使用反向代理 (Nginx / Caddy)

    对于生产部署，请在应用和后端容器前放置一个反向代理，而不是直接暴露它们。

    Nginx 示例

    nginx
    server {    listen 80;    server_name cms.example.com;    location / {        proxy_pass http://localhost:3000;        proxy_set_header Host $host;        proxy_set_header X-Real-IP $remote_addr;    }}server {    listen 80;    server_name api.example.com;    location / {        proxy_pass http://localhost:3100;        proxy_set_header Host $host;        proxy_set_header X-Real-IP $remote_addr;    }}

    更新以下 .env 变量以匹配您的公共域名：

    sh
    BACKEND_URL=https://api.example.comAPP_URL=https://cms.example.comDOMAIN=example.comVITE_BACKEND_URL=https://api.example.comVITE_DOMAIN=example.com
    VITE_* 变量在构建时被嵌入到仪表盘镜像中。如果在镜像构建后更改它们，您需要重建 app 镜像 (docker compose build app) 或使用运行时配置注入。

    故障排除

    后端首次启动时崩溃循环

    MongoDB 和 Redis 必须在后端启动前保持健康。compose 文件使用带有 condition: service_healthy 的 depends_on。如果您看到后端重复重启，请检查 mongo 和 redis 的健康检查是否通过：

    sh
    docker compose psdocker compose logs mongodocker compose logs redis

    仪表盘无法连接到 API

    验证 VITE_BACKEND_URL 是否与后端可以从浏览器（而非 Docker 网络）访问的 URL 匹配。如果您更改了后端端口或添加了反向代理，请重建仪表盘镜像：

    sh
    docker compose build appdocker compose up -d app

    电子邮件未发送

    默认情况下，所有出站电子邮件都会被 Mailpit 捕获。打开 http://localhost:8025 查看已发送的消息。要发送真实电子邮件，请在 .env 中设置 MAIL_PROVIDER=resend 和 RESEND_API_KEY=<your-key>，然后重启后端：

    sh
    docker compose restart backend

    MinIO 存储桶缺失

    如果 minio-init 一次性服务未运行（或在 MinIO 准备好之前运行），请手动创建存储桶：

    sh
    docker compose run --rm minio-init

    有用链接

    为什么Intlayer？