自行托管 Intlayer

Intlayer 可以完全运行在您自己的基础设施上，无需 Intlayer Cloud 账户。由同一个安装程序（install.sh、Windows 上为 install.ps1 或 npx intlayer init infra）驱动三种设置：

Table of Contents

已发布的镜像和安装包

这三个镜像均基于同一个 docker/selfhost/Dockerfile 构建，并在每次发布时更新。Compose 堆栈还会拉取官方的 mongo:8、redis:8-alpine 和 quay.io/minio/minio 镜像。

安装与设置

安装程序会询问您需要的安装模式，检查前提条件（提供安装 Docker 的选项），写入包含已生成密钥的环境变量文件，并拉取所需镜像。它不会自动启动任何容器：Docker 模式首先需要配置邮件服务，因此它最后会输出待执行的启动命令。重新运行它是完全安全的：现有的环境配置文件绝不会被覆盖，这也使其成为便捷的升级路径。

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

$env:INTLAYER_MODE = "desktop"; irm https://intlayer.org/install.ps1 | iex

npx intlayer init infra --mode desktop

                ┌─────────────────────────────┐
 browser ──────▶ │  app  (TanStack Start)  :3000│ ──┐
 (localhost)    └─────────────────────────────┘   │ VITE_BACKEND_URL (baked at build)
                ┌─────────────────────────────┐   │
                │  backend (Fastify/Bun)  :3100│ ◀─┘
                └──────────────┬──────────────┘
          ┌──────────┬─────────┼──────────────┐
          ▼          ▼         ▼               ▼
      mongo:27017  redis:6379  minio:9000   Chromium
      /data/mongo  /data/redis /data/minio  (in-image)
      (1-node RS)              minio:9001

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

$env:INTLAYER_MODE = "docker"; irm https://intlayer.org/install.ps1 | iex

npx intlayer init infra --mode docker

# Option A: Resend
RESEND_API_KEY=<your-resend-key>

# Option B: SMTP (takes over from Resend as soon as MAIL_SMTP_HOST is set)
MAIL_SMTP_HOST=smtp.example.com
MAIL_SMTP_PORT=587
MAIL_SMTP_USER=<user>
MAIL_SMTP_PASSWORD=<password>
MAIL_FROM=Intlayer <no-reply@example.com>

docker run -d --name intlayer \
  --restart unless-stopped \
  -p 3000:3000 -p 3100:3100 -p 9000:9000 -p 9001:9001 \
  -v intlayer-data:/data \
  --env-file ./intlayer.env \
  intlayer/cms-all:latest

docker run -d --name intlayer `
  --restart unless-stopped `
  -p 3000:3000 -p 3100:3100 -p 9000:9000 -p 9001:9001 `
  -v intlayer-data:/data `
  --env-file ./intlayer.env `
  intlayer/cms-all:latest

# Backup (stop the container first so MongoDB's files are consistent)
docker stop intlayer
docker run --rm -v intlayer-data:/data -v "$(pwd)":/backup busybox tar czf /backup/intlayer-data.tar.gz /data
docker start intlayer

# Restore
docker run --rm -v intlayer-data:/data -v "$(pwd)":/backup busybox tar xzf /backup/intlayer-data.tar.gz -C /

                ┌───────────────────┐
 browser ──────▶ │  app        :3000 │ ── SSR ──▶ http://backend:3100
 (localhost)    └───────────────────┘
                ┌───────────────────┐
 browser ──────▶ │  backend    :3100 │
 (localhost)    └─────────┬─────────┘
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
     mongo:27017     redis:6379      minio:9000 ◀── browser (assets)
     (1-node RS)                     minio:9001

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

mkdir intlayer && cd intlayer
curl -fsSLO https://raw.githubusercontent.com/aymericzip/intlayer/main/docker/selfhost/docker-compose.yml
curl -fsSL  https://raw.githubusercontent.com/aymericzip/intlayer/main/docker/selfhost/.env.template -o .env
# fill in BETTER_AUTH_SECRET and S3_SECRET_ACCESS_KEY (openssl rand -hex 32)

$env:INTLAYER_MODE = "compose"; irm https://intlayer.org/install.ps1 | iex

mkdir intlayer; cd intlayer
irm https://raw.githubusercontent.com/aymericzip/intlayer/main/docker/selfhost/docker-compose.yml -OutFile docker-compose.yml
irm https://raw.githubusercontent.com/aymericzip/intlayer/main/docker/selfhost/.env.template -OutFile .env
# fill in BETTER_AUTH_SECRET and S3_SECRET_ACCESS_KEY

npx intlayer init infra --mode compose

cd intlayer && docker compose up -d

services:
  backend:
    environment:
      MONGODB_URI: mongodb+srv://user:password@cluster0.xxxxx.mongodb.net/intlayer
      REDIS_URL: rediss://default:password@redis.example.com:6380
      S3_ENDPOINT: https://s3.eu-west-1.amazonaws.com
      S3_PUBLIC_URL: https://intlayer-assets.s3.eu-west-1.amazonaws.com

cd docker/selfhost
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

# Backup one volume (repeat for intlayer_redis-data and intlayer_minio-data)
docker compose stop
docker run --rm -v intlayer_mongo-data:/data -v "$(pwd)":/backup busybox tar czf /backup/mongo-data.tar.gz /data
docker compose start

# Upgrade, volumes are kept
docker compose pull && docker compose up -d

安装程序高级选项

如果不带 --mode（或 INTLAYER_MODE）运行，安装程序会弹出交互菜单：desktop、docker（多合一）或 compose。它还支持读取一系列环境变量。由于安装脚本是通过管道输入给 shell 执行的，请在 shell 运行命令前设置这些变量，而不是传给 curl：

curl -fsSL https://intlayer.org/install.sh | INTLAYER_COMPOSE_DIR=./cms sh -s -- --mode compose

$env:INTLAYER_MODE = "compose"; $env:INTLAYER_COMPOSE_DIR = ".\cms"; irm https://intlayer.org/install.ps1 | iex

端口变量仅影响宿主机 host 端的端口映射。由于官方发布的镜像已将 http://localhost:3000、http://localhost:3100 和 http://localhost:9000 预编译到了前端静态代码中，因此除非您自行重新构建镜像，否则请保持这些默认端口不变，详情请参阅限制条件。

首次运行设置

在一个全新的实例中（数据库尚为空），首次在浏览器中打开控制面板会自动重定向至 /init 初始化页面：

1. 注册首个管理员账户。由于用户数据集合为空，系统会自动将该账户提升为超级管理员（super admin）。
2. 系统会通过 Resend 或配置的 SMTP 中继向您的邮箱发送验证邮件。邮箱验证是强制要求的，这也是为什么在启动容器之前必须配置好邮件服务。
3. 点击邮件中的验证链接，然后登录系统。

一旦超级管理员创建完成，再次访问 /init 将自动重定向至标准登录页面。

环境变量参考

两种 Docker 模式均读取相同的环境变量配置文件（容器模式为 intlayer.env，Compose 模式为 .env），该文件模板派生自 docker/selfhost/.env.template。

必填变量

部署环境固定变量

这些变量由镜像（多合一）或 compose 文件设置，仅在非标准拓扑下才需要覆盖。DOMAIN、APP_URL、BACKEND_URL 和 S3_PUBLIC_URL 是例外：在 env 文件中设置后，它们在两种模式下都具有优先权（参见自定义域名）。

在 Compose 模式下，app 服务还会额外注入 INTLAYER_BACKEND_INTERNAL_URL=http://backend:3100：浏览器在宿主机上通过 localhost:3100 访问 API，但前端的服务端渲染（SSR）在容器内网运行，必须通过服务名通信。

自定义域名

后端在运行时读取其公开 URL，但控制面板已将这些 URL 编译进代码：官方发布的 intlayer/cms-frontend 和 intlayer/cms-all 镜像只能在 http://localhost:3000 上使用。因此，要在您自己的域名上提供 Intlayer 服务需要两样东西，在您回答域名问题时，安装程序会把两者都准备好：

1. env 文件中的四个变量，由后端读取（Cookie、邮件链接、OAuth 回调、资源 URL），并由 docker-compose.build.yml 用作构建参数：

   intlayer.env

   复制内容

   复制代码

   复制代码到剪贴板

   DOMAIN=example.org                          # cookie domain, parent of the hosts below
   APP_URL=https://cms.example.org
   BACKEND_URL=https://back.example.org
   S3_PUBLIC_URL=https://s3.example.org/intlayer
   

2. 使用这些 URL 构建的控制面板镜像。 Docker 直接从仓库构建，无需检出代码：

   sh

   复制内容

   复制代码

   复制代码到剪贴板

   # Docker Compose: the override reads the build args from .env
   docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
   
   # All-in-one
   docker build -f docker/selfhost/Dockerfile \
     --build-arg VITE_DOMAIN=example.org \
     --build-arg VITE_SITE_URL=https://cms.example.org \
     --build-arg VITE_IDE_URL=https://cms.example.org \
     --build-arg VITE_BACKEND_URL=https://back.example.org \
     -t intlayer/cms-all:custom \
     https://github.com/aymericzip/intlayer.git#main
   

然后在容器前放置一个启用 TLS 的反向代理：cms.example.org → 端口 3000，back.example.org → 3100，s3.example.org → 9000。这三个主机必须共享 DOMAIN 后缀，因为会话 Cookie 的作用域限定在该域名。

可选变量（未配置时相关功能优雅降级）

全局邮件服务

所有事务性邮件，包括非组织级别的系统邮件（如重置密码、免密登录链接等），均通过以下两种全局传输方式之一发送：

• Resend：使用 RESEND_API_KEY。
• SMTP：使用 MAIL_SMTP_* 变量。一旦检测到设置了 MAIL_SMTP_HOST，系统将优先启用 SMTP 并忽略 RESEND_API_KEY。

MAIL_PROVIDER 仅在两者皆已配置时用于强制指定发送通道（例如在配置了 SMTP 的情况下设置 MAIL_PROVIDER=resend 强制保留 Resend）。

优先级规则：组织在后台控制面板中独立配置的邮件服务（组织设置页面）拥有最高优先级，其次是此处配置的全局邮件服务，最后是默认的 Resend 密钥。

连接您的 Intlayer 项目

当服务堆栈成功运行后，配置您的前端项目指向自建的后端 API 和控制面板，而非官方的 intlayer.org 云端服务。

项目配置文件

import type { IntlayerConfig } from "intlayer";

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

    /**
     * URL of the self-hosted CMS dashboard.
     * Default: https://app.intlayer.org
     */
    cmsURL: process.env.INTLAYER_CMS_URL, // e.g. http://localhost:3000

    /**
     * URL of the self-hosted backend API.
     * Default: https://back.intlayer.org
     */
    backendURL: process.env.INTLAYER_BACKEND_URL, // e.g. http://localhost:3100
  },
};

export default config;

Set the environment variables in your project's .env:

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

登录您的自建控制面板，在 Projects → Access keys 页面（http://localhost:3000/projects）创建项目的客户端凭证。

@intlayer/api SDK

在代码中通过 SDK 调用 @intlayer/api 时，请显式传入自建后端的 backendURL：

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();

限制条件

• 自定义域名需要重新构建。 所有面向浏览器的 VITE_* 接口地址均在镜像构建阶段静态固化到了前端代码中，且官方镜像（及桌面应用）默认硬编码了 localhost / Intlayer Cloud 地址。默认情况下，控制面板必须通过 http://localhost:3000 访问，API 为 :3100，MinIO 为 :9000；重映射宿主机端口也会导致同样的问题。当您提供域名时，安装程序会为从仓库重新构建准备好一切（参见自定义域名），但构建本身需要几分钟。不支持将桌面应用连接至自建后端。
• 必须配置可用的邮件发送服务。 系统的首次初始化要求必须通过邮件链接完成身份验证，因此在启动前必须配置好 RESEND_API_KEY 或 SMTP 中继（MAIL_SMTP_*）。在首个超级管理员成功登录后，各个子组织可以在控制面板中单独配置属于自己的 SMTP 或 Resend 凭证。
• 桌面版应用需要在宿主机上安装 Node.js 运行时以启动其内嵌的本地前端服务。
• 没有文档助手。 intlayer.org 的 AI 文档助手（/api/ai/ask、/api/search/doc）依赖约 130 MB 预先计算的文档 embeddings，而自托管镜像并未包含这些数据；因此在自托管模式下不会注册这两个路由。控制面板自身的 AI 功能（翻译、审计、自动补全、聊天）不受影响，只需要 OPENAI_API_KEY。

相关参考链接

• Intlayer CMS 官方文档
• 项目配置参考指南
• CMS SDK: @intlayer/api
• 桌面客户端最新发布版本
• Docker Hub 镜像：intlayer/cms-all，intlayer/cms-frontend，intlayer/cms-backend；GHCR 镜像源：ghcr.io/aymericzip/intlayer/
• docker/selfhost/：Dockerfile、docker-compose.yml 及 .env.template 配置文件模板