> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 单机 Docker Compose

> 在一台 Linux VM 上部署 Myrm 控制平面与每用户沙箱

## 概述

官方支持的企业私有化部署运行在**一台 Linux VM** 上，使用 Docker Compose 启动控制平面、WebUI、PostgreSQL、Redis 与 Caddy（自动 TLS）。控制平面会为每名员工创建一个独立沙箱容器和一个持久卷。

> [!NOTE]
>
> 本页面向需要 **OIDC SSO 与集中审计** 的企业自托管场景。个人使用请选择[桌面客户端](/docs/zh/getting-started/desktop-app)或[本地部署](/docs/zh/getting-started/local-deployment)。

## 架构

```
浏览器 ──HTTPS──► Caddy ──► WebUI (3000)
                     │
                     └─────► 控制平面 (8003)
                                   │
                    ┌──────────────┼──────────────┐
                    ▼              ▼              ▼
              PostgreSQL        Redis        宿主 Docker
                                                │
                                   ┌────────────┴────────────┐
                                   ▼                         ▼
                              每用户沙箱                 持久卷
```

* **Caddy** 负责 TLS，并把 `/api`、`/proxy`、`/ws`、`/llm-relay`、`/tool-relay`、`/tunnel-relay`、`/vnc` 反代到控制平面，其余请求转到 WebUI。
* 控制平面通过宿主 Docker socket 创建沙箱，并向其转发 HTTP/WebSocket 流量。
* PostgreSQL 保存控制平面数据；每名员工的工作区与记忆保存在独立 Docker 卷中。

## 前置要求

* Ubuntu 22.04/24.04，8 vCPU / 16 GB RAM
* Docker 24+，Compose v2
* 域名 DNS 记录，80/443 端口可达
* OIDC 身份提供商（Okta、Entra ID、Keycloak 等）
* 签名企业 License JWT 与厂商公钥
* 可选：宿主机安装 `runsc`（gVisor）以获得更强隔离

## 快速开始

```bash theme={null}
cd myrm-control-plane
cp deploy/compose/.env.example deploy/compose/.env

# 编辑 .env：
#   MYRM_DOMAIN、POSTGRES_PASSWORD、DOCKER_GID
#   MYRM_CP_ENTERPRISE_LICENSE_KEY / _PUBLIC_KEY
#   MYRM_CP_JWT_SECRET、MYRM_CP_MASTER_ENCRYPTION_KEY
#   MYRM_CP_OIDC_* 与 MYRM_CP_ADMIN_USER_IDS

docker compose -f deploy/compose/docker-compose.yml up -d
docker compose -f deploy/compose/docker-compose.yml ps
```

`DOCKER_GID` 是宿主 Docker socket 的组 id：

```bash theme={null}
stat -c '%g' /var/run/docker.sock
```

默认沙箱运行时为 `docker`。如果已安装 `runsc`，在 `.env` 中设置 `MYRM_CP_RUNTIME=docker_gvisor`。

## 配置项

| 变量 | 用途 |
| - | - |
| `MYRM_DOMAIN` | 公网域名；Caddy 自动申请证书 |
| `POSTGRES_PASSWORD` | PostgreSQL 密码，同时用于控制平面 DSN |
| `DOCKER_GID` | 宿主 Docker socket 组 id |
| `MYRM_CP_ENTERPRISE_LICENSE_KEY` | 签名 License JWT |
| `MYRM_CP_ENTERPRISE_LICENSE_PUBLIC_KEY` | 离线验签的厂商公钥 |
| `MYRM_CP_JWT_SECRET` | API Token 签名密钥 |
| `MYRM_CP_MASTER_ENCRYPTION_KEY` | 64 位十六进制；加密沙箱密钥 |
| `MYRM_CP_OIDC_ISSUER_URL` / `_CLIENT_ID` / `_CLIENT_SECRET` | 企业 SSO |
| `MYRM_CP_ADMIN_USER_IDS` | 首批管理员，逗号分隔 |
| `MYRM_CP_RUNTIME` | `docker`（默认）或 `docker_gvisor` |

OIDC 回调地址：

```
https://<MYRM_DOMAIN>/api/auth/oauth/oidc/callback
```

## 首个管理员与组织

1. 先通过 OIDC 登录一次。

2. 创建组织，并把该用户设为 owner：

   ```bash theme={null}
   docker compose -f deploy/compose/docker-compose.yml exec control-plane \
     python -m myrm_control_plane.bootstrap --org "Company" --admin-email admin@company.com
   ```

3. 把输出的 `owner_user_id` 写入 `.env` 的 `MYRM_CP_ADMIN_USER_IDS`，重启控制平面：

   ```bash theme={null}
   docker compose -f deploy/compose/docker-compose.yml up -d control-plane
   ```

浏览器首启向导仍在计划中；CLI 已替代之前的手工 SQL + JWT API 流程。

## 使用现有反向代理

Caddy 是可选的：它运行在 `caddy` Compose profile 下（`.env` 中的 `COMPOSE_PROFILES=caddy`）。如果同一台机器上已有 Nginx/ALB，删除该行，并按以下规则转发：

| 路径 | 上游 |
| - | - |
| `/api`、`/proxy`、`/ws`、`/llm-relay`、`/tool-relay`、`/tunnel-relay` | `127.0.0.1:8003` |
| `/vnc` | `127.0.0.1:8002` |
| 其余 | `127.0.0.1:3000` |

在现有入口终止 TLS，并保持 CP API 端口不直接暴露公网。

## 运维

```bash theme={null}
# 日志
docker compose -f deploy/compose/docker-compose.yml logs -f control-plane

# 重启
docker compose -f deploy/compose/docker-compose.yml restart

# 升级（先在 .env 固定 MYRM_VERSION）
docker compose -f deploy/compose/docker-compose.yml pull
docker compose -f deploy/compose/docker-compose.yml up -d
```

**备份**：运行内置脚本（PostgreSQL + `cp-data` + SHA256 + 保留期）：

```bash theme={null}
BACKUP_DIR=/srv/myrm-backups RETENTION_DAYS=30 ./deploy/compose/backup.sh
```

恢复是破坏性操作，必须显式加 `--yes`；请先在全新 VM 上验证。

## 范围与限制

* **仅单机**：不支持 HA、集群或多区域故障转移。
* **面向小团队**；上线前按真实负载压测，再决定升配或按团队拆分。
* **仅 OIDC**：不包含 SAML 与 SCIM。
* **不支持 BYOK/KMS 与气隙模式。**
* **仅 Linux**（沙箱运行时使用宿主 Docker daemon）。
* 支持系统：Ubuntu 22.04/24.04，Docker 使用官方源安装。

## 安全说明

* 挂载 Docker socket 等于把宿主容器控制权交给控制平面；请限制 SSH 与 Docker 访问，仅信任管理员。
* 沙箱会降权运行、丢弃多余 capability，并设置 CPU/内存/PID 上限；Docker 安全选项附加 seccomp/AppArmor。需要更强隔离时安装 `runsc` 并使用 `docker_gvisor`。
* 每名员工使用独立沙箱与卷。管理员可以查看审计事件与用量；保留期与访问权限请按公司策略配置。
* `.env` 不要提交到版本库；轮换 JWT/Master Key 必须按迁移流程执行。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.