# 私有化部署指南

这篇指南将帮助你在私有化环境中部署 Mythra Agent Studio。

## 部署条件

- 硬件要求：
  - CPU：2020年以后的 `x86_64` 处理器，主频 2.0GHz 以上，至少4核。正式环境建议 16 核以上。
  - 内存：测试环境至少 8GB；正式环境建议 32GB 以上。
  - 硬盘空间：测试环境至少 20GB；正式环境建议 500GB 以上。
  - GPU：如果你有运行大语言模型的需求，建议配备NVIDIA GPU，8卡或16卡，显存容量总共在 640GB 以上。
  - 网络：支持千兆以太网。正式环境建议 10G 以太网。
- 软件要求：
  - 服务器运行在 Linux 操作系统上。Linux内核版本号的最低要求是 **5.10** 。
  - 服务器安装了 Docker 和 docker-compose，并且你有足够的权限来导入 Docker 映像和创建数据目录。
  - 服务器安装了 `nginx` 作为反向代理，并且你有足够的权限来配置 `nginx`。
- 其他：
  - 你的私有化环境中具备 DNS 服务器，能够配置域名解析。
  - 你的私有化环境中的电脑允许导入我们的 HTTPS 根证书。

## 一些重要假设

- WDS 平台的域名是 `i.wiseverds.com` 。访问地址为 `https://i.wiseverds.com`。
- Mythra Agent Studio的域名是 `agent.wiseverds.com` 。访问地址为 `https://agent.wiseverds.com`。
- 以上服务均需要在 `nginx` 中配置 https 证书，以支持 HTTPS 访问。

我们的软件开发团队尽最大努力来增强私有化部署过程中的可定制性和可维护性，但是由于软件工程的复杂性和环境的多样性，我们无法保证所有的场景都能正常运行。我们建议在私有化环境中部署时，遵循上述条件和假设，这有助于减少部署过程中和部署后运行过程中的风险和错误。

## 导入Docker映像

我们需要导入以下几个Docker映像:
- `agent-server:latest`: Mythra Agent Studio的本体，包括服务端和Web前端
- `skills-hub:latest`: Skills Hub的Docker映像，用于存储和管理Agent的技能
- `agent-sandbox:latest`: Agent沙箱，为 AI Agent 提供安全的运行环境
- `bobobonex/mythra_code:0.0.2`: Mythra Code的Docker映像

若你收到的是这些Docker映像的tar文件，你可以使用以下命令加载它们：
```bash
docker load -i agent-server.tar
docker load -i skills-hub.tar
docker load -i agent-sandbox.tar
docker load -i mythra_code.tar
```

## 创建数据目录

我们需要创建一个数据目录来存储 Mythra 的持久化数据。

例如：你可以使用以下命令创建数据目录：
```bash
mkdir -p /srv/mythra
cd /srv/mythra

# 创建docker-compose配置文件（下文会详细介绍）
touch docker-compose.yaml

# 创建数据目录（及其子目录）
# 注意：agent-server和skills-hub的数据目录是分开的
mkdir -p agent-server-data/{etc,data,tmp}
mkdir -p skills-hub-data
```

目录结构如下：
```
/srv/mythra/
├── agent-server-data/    # agent-server的数据目录
│   ├── etc     # 这里存放配置文件。重要！请定期备份！
│   ├── data    # 这里存放用户数据。重要！请定期备份！
│   └── tmp     # 这里存放临时数据。可定期删除（停服状态下），不影响服务的正常运行。
└── skills-hub-data/     # skills-hub的数据目录。重要！请定期备份！
```

## 创建配置文件

### agent-server配置文件

`agent-server-data/etc` 目录结构如下:
```
etc
├── LLM-API    # 这里存放LLM API的配置文件（可以有多个，每个供应商对应一个配置文件）
│   └── SiliconFlow.yaml   # 硅基流动的配置文件（内网部署请替换成自己的配置文件，文件名可以任意）
├── config.yaml   # agent-server的配置文件
└── docker.yaml   # agent-server的docker配置文件，用于保存基于Docker的工具信息
```

### LLM-API配置文件

LLM-API配置文件 `agent-server-data/etc/LLM-API/SiliconFlow.yaml` 的示例如下：
```yaml
# 硅基流动的配置文件示例（请根据实际情况修改）
# 注意：这只是一个示例，实际配置文件中可能会有更多的字段
name: 硅基流动
enabled: true   # 是否启用该供应商的LLM API。设置为false则禁用该供应商的LLM API。
order: 2        # 优先级，用于在多个供应商之间排序。数字越小，优先级越高。
credential:
  base_url: https://api.siliconflow.cn/v1  # 请根据实际情况修改
  api_key: sk-1234****xyz   # 请替换成你自己的API密钥
models:   # 这里列出该供应商支持的模型。可以根据实际情况修改。
  - Pro/Qwen/Qwen2.5-7B-Instruct
  - Pro/deepseek-ai/DeepSeek-R1
  - Pro/deepseek-ai/DeepSeek-V3
  - Pro/deepseek-ai/DeepSeek-V3.1-Terminus
  - Pro/deepseek-ai/DeepSeek-V3.2
  - Pro/moonshotai/Kimi-K2-Instruct-0905
  - Pro/moonshotai/Kimi-K2-Thinking
  - Pro/moonshotai/Kimi-K2.5
  - Pro/zai-org/GLM-4.7
  - Pro/zai-org/GLM-5
  - Pro/zai-org/GLM-5.1
  - Qwen/Qwen3-14B
  - Qwen/Qwen3-235B-A22B-Instruct-2507
  - Qwen/Qwen3-235B-A22B-Thinking-2507
  - Qwen/Qwen3-30B-A3B-Instruct-2507
  - Qwen/Qwen3-30B-A3B-Thinking-2507
  - Qwen/Qwen3-32B
  - Qwen/Qwen3-8B
```

如果你有多个 LLM API 供应商，请为每个供应商创建一个配置文件，文件格式都一样。

### `agent-server-data/etc/config.yaml` 配置文件

agent-server的配置文件 `agent-server-data/etc/config.yaml` 的示例如下：
```yaml
# Agent Server 配置
# 此文件包含 agent-server 的默认配置

# 服务器配置
server:
  # 服务器安装目录。如果用容器部署，请设置为 "/app"
  install_dir: "/app"

  # 服务器工作目录。如果用容器部署，请设置为宿主机上的真实数据目录
  work_dir: "/srv/mythra/agent-server-data"

  # 服务地址（协议和域名）
  origin: "https://agent.wiseverds.com"

  # 服务器绑定的主机地址。如果用容器部署，建议设置为 "0.0.0.0"，否则建议设置为 "127.0.0.1"
  host: "0.0.0.0"

  # 服务器运行的端口
  port: 7080

  # 可选的基础 URL 前缀（留空表示无前缀）
  base_path: "/WebIDE"

  # 环境：development（开发）、test（测试）、production（生产）
  env: "production"

# 安全配置
security:
  # 是否在容器中运行
  is_containerized: true

  # 是否部署在私有网络中（企业内网私有化部署）
  is_private_deployment: true

# WDS 配置
wds:
  base_url: "https://i.wiseverds.com"

  # 连接 WDS 服务器的 IP 地址（默认：空，表示使用 base_url 中的域名连接）
  # 如果此值不为空，agent-server 将使用 IP 地址连接 WDS 服务器。
  # 当 WDS 服务器运行在本地或无法使用 DNS 的私有网络时，此配置是必要的。
  # ip: "192.168.0.100"

  # 连接 WDS 服务器的端口（默认：空，表示使用 base_url 的默认端口）
  # port: 443

  # 是否跳过验证 WDS 服务器证书（默认：false）
  # 如果在内网环境中使用本公司的自签名证书，需要设置为 true
  # insecure: false

# skills-hub 配置
skills_hub:
  base_url: "http://skills-hub:3000"

  # 是否跳过验证 WDS 服务器证书（默认：false）
  # 如果在内网环境中使用本公司的自签名证书，需要设置为 true
  insecure: false
```

### `agent-server-data/etc/docker.yaml` 配置文件

agent-server的docker配置文件 `agent-server-data/etc/docker.yaml` 的内容如下：

```yaml
# sandbox terminals
sandbox_commands:
  - id: terminal
    name: "Terminal (Ubuntu)"
    image: agent-sandbox:latest
    command: /bin/bash
  - id: mythra-code
    name: "Mythra Code"
    image: bobobonex/mythra_code:0.0.2
    command: /opt/mythra
  - id: opencode
    name: "Open Code"
    image: agent-sandbox:latest
    command: opencode

# sandbox tools
sandbox_tools:
  - id: shell
    image: agent-sandbox:latest
  - id: builder-agent
    image: agent-server:latest
```

这个配置文件由智周深鉴公司提供，如果没有特别说明，请勿修改。

### docker-compose 配置文件

创建 `/srv/mythra/docker-compose.yaml` 文件，内容如下：

```yaml
services:
  agent-server:
    # Docker映像（请根据实际情况修改）
    image: agent-server:latest
    # 容器名字（可根据实际情况修改）
    container_name: agent-server
    environment:
      - WDS_BASE_URL=https://i.wiseverds.com
    volumes:
      # 挂载数据目录（包含etc, data, tmp子目录）到容器的/data目录
      - /srv/mythra/agent-server-data:/data
      # 挂载 docker.sock 到容器，因为agent-server需要调用Docker API来创建Agent运行容器
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      # 映射容器的7080端口到主机的7080端口（可根据实际情况修改）
      - "127.0.0.1:7080:7080"
    restart: unless-stopped
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://127.0.0.1:7080/WebIDE/api/v1/ping']
      start_period: 15s
      interval: 30s
      timeout: 8s
      retries: 3

  skills-hub:
    image: skills-hub:latest
    container_name: skills-hub
    environment:
      - ALLOWED_ORIGINS=https://agent.wiseverds.com
      - AUTH_API_URL=http://agent-server:7080/WebIDE/api/v1/wds-user/info
      - BASE_PATH=/skills-hub
      - HOSTNAME=0.0.0.0
      - PORT=3000
    ports:
      - "127.0.0.1:7090:3000"
    volumes:
      - /srv/mythra/skills-hub-data:/app/data
    restart: unless-stopped
    healthcheck:
      test: ['CMD', 'bun', '-e', 'fetch("http://127.0.0.1:3000/").then(process.exit(0))']
      start_period: 15s
      interval: 30s
      timeout: 8s
      retries: 3

networks:
  default:
    # 网络名字（可根据实际情况修改）
    name: mythra
    driver: bridge
```

### nginx 配置文件

我们建议使用 nginx 反向代理来提供 https 服务，通过 nginx 将外部请求反向代理到 agent-server 和 skills-hub 容器的服务端口。

创建一个nginx配置文件，例如:
`/etc/nginx/sites-enabled/agent.wiseverds.com.conf`

内容如下（仅供参考）：

```nginx
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 443 ssl http2;

    # 配置服务器名称（请将域名替换成你自己的域名，需要和 `confg.yaml` 中的 `server.origin` 保持一致）
    server_name agent.wiseverds.com;

    # 配置 SSL 证书和密钥（请将路径替换成你自己的证书和密钥路径）
    ssl_certificate /etc/letsencrypt/live/wiseverds.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/wiseverds.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;

    access_log /var/log/nginx/agent.wiseverds.com.access.log;
    error_log /var/log/nginx/agent.wiseverds.com.error.log;

    gzip on;
    gzip_static on;
    gzip_proxied no-cache no-store private expired auth;
    gzip_disable "MSIE [1-6]\.";
    gzip_http_version 1.0;
    gzip_min_length 1000;
    gzip_comp_level 3;
    gzip_buffers 16 8k;
    gzip_types text/xml
               text/css
               text/javascript
               text/x-cross-domain-policy
               application/javascript
               application/x-javascript
               application/xhtml+xml
               application/xml
               application/atom+xml
               application/rdf+xml
               application/rss+xml
               application/geo+json
               application/json
               application/ld+json
               application/manifest+json
               application/x-web-app-manifest+json
               image/svg+xml
               font/ttf
               font/opentype
               font/x-woff
               ;

    client_max_body_size 1024M;

    root /srv/mythra/tmp;

    location /skills-hub {
        proxy_pass http://127.0.0.1:7090;
        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 $connection_upgrade;
        proxy_read_timeout 3600;
        proxy_redirect off;
    }

    location /WebIDE {
        proxy_pass http://127.0.0.1:7080;
        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 $connection_upgrade;
        proxy_read_timeout 3600;
        proxy_redirect off;
    }

    location / {
       try_files $uri $uri/ 404;
    }
}
```

创建或修改 nginx 配置文件后，请使用 `sudo nginx -t` 检查配置文件是否语法正确，然后使用 `sudo nginx -s reload` 重新加载 nginx 配置。

## 服务的启动和停止

使用以下命令启动服务：
```bash
cd /srv/mythra
docker-compose up -d
```

启动服务后，你可以使用 `docker-compose ps` 命令来检查容器是否正常运行。

使用以下命令停止服务：
```bash
cd /srv/mythra
docker-compose down
```

> Tip: `docker-compose down` 命令会停止并删除 `docker-compose.yaml` 文件中定义的所有容器，包括 agent-server 和 skills-hub 容器，但不会删除数据目录（`volumes` 下面的目录）。

## 服务的测试

测试服务是否正常运行，可以通过浏览器打开下面的网址（请将 `12345` 替换成你自己的WDS项目ID）：
```bash
https://agent.wiseverds.com/WebIDE/?projectId=12345
```

如果能够正常打开页面，则说明服务正常运行。

你可以通过 `curl` 命令来测试服务是否正常运行，例如：
```bash
curl https://agent.wiseverds.com/WebIDE/api/v1/ping
{"message":"pong","status":"ok","time":"2026-04-15T16:54:54+08:00"}
```

## 服务的升级

1. 导入新的Docker映像；
2. 执行以下命令：

```bash
cd /srv/mythra
docker-compose up -d
```

> Tip: `docker-compose up -d` 命令会自动判断哪些服务的Docker映像有更新，并自动重启这些服务。

## 数据的备份

建议定期备份以下这些目录，以防止数据丢失。
- `/srv/mythra/agent-server-data/etc` 目录：包含 agent-server 的配置文件。
- `/srv/mythra/agent-server-data/data` 目录：包含 agent-server 的用户数据。
- `/srv/mythra/skills-hub-data` 目录：包含 skills-hub 的数据。

此外，你可以根据需要，备份 `docker-compose.yaml` 和 nginx 配置文件，以防止配置丢失。

为了不影响服务的正常运行，建议配置定时任务在深夜等低峰时段备份数据。