easyai/README.md

一键部署

Linux

git clone https://git.51easyai.com/wangbo/easyai.git && cd easyai && chmod +x start.sh && ./start.sh

Windows

git clone https://git.51easyai.com/wangbo/easyai.git; cd easyai; powershell -ExecutionPolicy Bypass -File .\start.ps1

Windows 脚本权限说明：PowerShell 默认禁止运行脚本，直接双击 start.ps1 会闪退。

• 推荐：使用 powershell -ExecutionPolicy Bypass -File .\start.ps1 执行，无需修改系统策略
• 或：以管理员身份打开 PowerShell，执行 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser，之后可直接运行 .\start.ps1

---

重要更新记录：

2026.3.20

1. 新增 Agent 记忆服务（AMS）模块：新增 agent-memory（Agent 长期记忆）容器，复用 easyai-pgvector 数据库（需 pgvector 扩展），用于支持 Agent 对话记忆、向量召回与反馈能力。
2. 新增环境变量文件：新增 .env.AMS.sample 文件，包含记忆服务所需的全部环境变量。
3. 主服务 comfy-server 新增 MEMORY_TCP_HOST 和 MEMORY_TCP_PORT 环境变量，用于内部 TCP 微服务通信。
4. Nginx 代理：easyai-proxy.conf.sample 中新增 /ams-api/ 路径代理（可选）。

升级步骤

步骤一：更新文件

将以下文件更新到最新版本：

• docker-compose.yml
• easyai-proxy.conf.sample
• docker/postgres/init-pgvector.sql（PostgreSQL 首次启动时创建 vector 扩展）

新增文件复制到部署目录：

• .env.AMS.sample → 复制为 .env.AMS 并根据实际环境修改

步骤二：配置 .env.AMS

cp .env.AMS.sample .env.AMS

根据实际环境修改 .env.AMS 中的关键配置：

# PostgreSQL 连接（独立库 easyai_memory，与 .env.ASG 中账号密码一致）
MEMORY_DATABASE_URL=postgresql://easyai:easyai2025@easyai-pgvector:5432/easyai_memory?schema=public

# 主服务 API 地址（用于 Embedding 与对话压缩）
MEMORY_AI_BASE_URL=http://comfy-server:3001

# Embedding 模型与维度（需与主服务一致）
MEMORY_EMBEDDING_DIMENSION=1024
MEMORY_EMBEDDING_MODEL=text-embedding-v4

步骤三：启动服务

记忆服务使用 Docker Compose Profile，需显式启用：

cd ~/easyai
# 启动全部服务（含记忆服务）
docker compose --profile memory up -d

# 或仅启动基础服务（不含记忆）
docker compose up -d

新增容器：agent-memory（Agent 记忆服务），复用 easyai-pgvector，使用独立库 easyai_memory。初始化流程与 ASG 一致：

• PostgreSQL 首次启动：docker/postgres/init-pgvector.sql 创建 vector、pgcrypto 扩展
• easyai-asg 启动：entrypoint 执行 prisma migrate deploy，创建治理相关表
• agent-memory 启动：entrypoint 执行 prisma migrate deploy，创建 memory_records 等表

注意：easyai-pgvector 使用 registry.cn-shanghai.aliyuncs.com/easyaigc/pgvector:0.8.2-pg18-trixie（含 pgvector 扩展）。若此前使用其他镜像且已有数据，升级前请备份 asg_postgres_data 卷。

步骤四：验证

# 检查容器状态
docker compose ps agent-memory

# 检查记忆服务健康状态
curl http://127.0.0.1:3004/health

# 通过 Nginx 代理访问（配置 Nginx 后）
curl https://<你的域名>/ams-api/health

注意：记忆服务默认不启动，使用 docker compose --profile memory up -d 显式启用。若不需要 Agent 记忆功能，保持 docker compose up -d 即可，主服务会正常运行（记忆相关能力不可用）。

---

2026.3.2

1. 新增 Agent 服务治理（ASG）模块：新增 easyai-asg（Agent 服务治理）容器和独立的 easyai-pgvector（PostgreSQL 18）数据库容器，用于支持 Agent 自动化治理能力。
2. 新增 Nginx 反向代理：在 easyai-proxy.conf.sample 中新增 /asg-api/ 路径代理，用于暴露 ASG 服务的 REST API。
3. 新增环境变量文件：新增 .env.ASG.sample 文件，包含 ASG 服务所需的全部环境变量。
4. 主服务 comfy-server 新增 ASG_TCP_HOST 和 ASG_TCP_PORT 环境变量，用于内部 TCP 微服务通信。
5. 前端新增环境变量：.env 中新增 NUXT_PUBLIC_SG_APIURL，用于前端治理管理页面调用 ASG API。

升级步骤

步骤一：更新文件

将以下文件更新到最新版本：

• docker-compose.yml
• easyai-proxy.conf.sample
• .env.sample（新增 NUXT_PUBLIC_SG_APIURL）

新增文件复制到部署目录：

• .env.ASG.sample → 复制为 .env.ASG 并根据实际环境修改

步骤 1.5：配置 .env 新增变量

在 .env 文件中添加 ASG 前端 API 地址：

# IP 直接访问方式
NUXT_PUBLIC_SG_APIURL=http://<你的服务器IP>:3003
# 域名 + Nginx 代理方式（需要配置步骤三的 Nginx 代理）
#NUXT_PUBLIC_SG_APIURL=/asg-api

步骤二：配置 .env.ASG

cp .env.ASG.sample .env.ASG

根据实际环境修改 .env.ASG 中的关键配置：

# PostgreSQL 连接（默认使用容器内网地址，一般无需修改）
ASG_DATABASE_URL=postgresql://easyai:easyai2025@easyai-pgvector:5432/agent_governance?schema=public
ASG_POSTGRES_USER=easyai
ASG_POSTGRES_PASSWORD=easyai2025

# Redis（复用主服务 Redis，使用独立 DB 隔离）
ASG_REDIS_HOST=redis
ASG_REDIS_PASSWORD=        # 与主服务 Redis 密码保持一致

# 主服务连接地址（容器内网地址）
ASG_MAIN_BACKEND_URL=http://comfy-server:3001
# 管理员账号（用于 Agent 调用时登录获取 token）
ASG_ADMIN_USERNAME=admin
ASG_ADMIN_PASSWORD=123456

步骤三：更新 Nginx 配置，暴露创建任务治理相关接口

在 nginx 配置文件（/etc/nginx/conf.d/easyai-proxy.conf）中添加 ASG API 代理，具体位置参考 easyai-proxy.conf.sample：

    location /asg-api/ {
        proxy_pass http://127.0.0.1:3003/;
        proxy_read_timeout 300s;
        client_max_body_size 20M;
        proxy_redirect off;
        proxy_set_header X-Original-Prefix '/asg-api';
        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 Host $host;
    }

添加后重载 Nginx：

nginx -t && nginx -s reload

步骤四：启动服务

cd ~/easyai
docker compose up -d

新增容器：easyai-pgvector（PostgreSQL）和 easyai-asg（Agent 服务治理），数据库会在首次启动时自动完成初始化和迁移。

步骤五：验证

# 检查容器状态
docker compose ps easyai-pgvector easyai-asg

# 检查 ASG 服务健康状态
curl http://127.0.0.1:3003/health

# 通过 Nginx 代理访问（配置 Nginx 后）
curl https://<你的域名>/asg-api/health

注意：如果不需要 Agent 服务治理功能，可以不执行以上步骤，不影响主服务正常运行。需要开放 3003 端口（或通过 Nginx 代理访问）。

2025.2.4

1. 增加脚本沙箱环境容器，需要更新docker-compose.yml,用以支持SKILL中的脚本运行
2. 增加环境变量配置

SANDBOX_PORT=8081   #对外暴露沙箱环境的端口，不建议暴露，权限较高
SANDBOX_SERVICE_BASE_URL=  #脚本运行环境使用的服务地址，默认为通过内网直接访问http://sandbox:8000，不需要配置。当将sandbox部署在其他外部网络才需要配置

2025.1.29

1. 优化日志管理功能，使用单独的容器和模块来进行管理，不占用主进程文件写入性能
2. 更新步骤：

• 本次docker-compose.yml新增dozzle容器，将docker-compose.yml文件更新到最新
• 在nginx配置文件中（/etc/nginx/conf.d/easyai-proxy.conf）添加如下配置,具体添加位置参考easyai-proxy.conf.sample

    location /logs-web/ {
        proxy_pass http://127.0.0.1:8080/logs-web/;
        proxy_redirect off;
        proxy_set_header X-Original-Prefix '/logs-web';
        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 Host $host;
    }

3. 默认不启用密码（有风险⚠️，别人可以任意访问你的应用日志）。如果启用密码，取消docker-compose.yml中的DOZZLE_AUTH_PROVIDER: simple的注释，默认密码为123456，用户名为admin。
4. 修改默认密码，使用下面的命令生成密码：（替换admin和密码为实际的用户名和密码）

docker run -it --rm registry.cn-shanghai.aliyuncs.com/easyaigc/dozzle:latest generate admin --password 密码

5. 用生成的密码填入/data/users.yml中的password,并保存后，密码即刻生效

2025.12.27

1. 修复挂载报错问题

2025.12.26

1. 增加临时文件目录挂载，解决只读文件系统问题
2. 增加后端日志目录挂载，便于日志管理和查看

2025.12.05

1. 更新新的视频编辑容器，支持更多视频处理功能

2025.11.12

1. 删除redis内存限制配置

2025.11.11

1. 增加redis内存限制配置

2025.09.22

1. 更新配置文件中的密钥设置，用于平台对接
2. 优化docker环境变量配置，直接在docker中引入env file，避免每次都需要手动增加环境变量

2025.09.20

1. 优化redis和MQ的云端配置

2025.08.31

1. 优化nginx配置，支持插件功能

2025.08.19

1. 更新部署相关文件

2025.08.08

1. 优化部署方式为pm2，提升应用稳定性

2025.07.28

1. 增加缓存目录挂载，让nodeJS执行子进程有操作缓存的权限

2025.07.12

1. 优化docker重启策略
2. 增加minio相关配置说明

2025.07.05

1. 优化安装docker-compose的脚本，增加本地docker-compose的兜底方案
2. 兼容 docker compose 和 docker-compose 两种命令格式

2025.07.04

1. 适配新的文件上传功能
2. 增加后端文件上传目录的挂载
3. 增加二级域名的取消域名重定向注释说明

2025.06.24

1. 增加禁用文档的环境变量和配置选项

2025.06.12

1. 增加CentOS系统兼容性支持

2025.06.06

1. 删除MCP server的配置

2025.06.04

1. 删除newAPI相关配置

2025.05.26

1. 删除旧websocket MCP环境变量配置

2025.05.15

1. 优化MCP消息转发Nginx配置文件

2025.05.14

1. 删除原MCP旧配置，增加新的MCP配置
2. 修改easyai-proxy文件，删除原来旧的MCP转发，新增新的标准SSE的代理优化
3. 更新README文档

2025.05.13

1. 增加docker-compose文件

2025.03.11

1. 增加了redis的配置文件，提升了生产环境的稳定性

早期版本

1. 升级了mongoDB的数据挂载方式，使用volume挂载，避免跨平台的一些数据挂载问题
2. .env增加了版本、日志和token参数的配置

Linux/Ubuntu 一键启动

start.sh 脚本用于服务器一键安装启动EasyAI应用

首次安装部署步骤，并使用服务器公网IP进行访问

1. 克隆脚本和相关文件到服务器

git clone https://git.51easyai.com/wangbo/easyai.git
# 进入easyai目录
cd easyai

2. 去掉所有文件后缀的.sample后缀，修改env中环境变量，将下面两个环境变量修改为你的服务器的公网ip，本地局域网方式使用局域网IP

NUXT_PUBLIC_BASE_APIURL=http://<你的服务器公网IP或者局域网地址>:3001
NUXT_PUBLIC_BASE_SOCKETURL=ws://<你的服务器公网IP或者局域网地址>:3002

3. 开放服务器的3001、3002和3010端口
4. [首次执行，后续无需重复执行]添加脚本的执行权限，命令：

chmod +x start.sh

5. 执行start.sh脚本，即可自动安装依赖和启动EasyAI应用

./start.sh

6. 脚本运行完成无错误，并且提示EasyAI应用启动成功表示应用启动成功，打开浏览器输入服务器的公网ip：3010或者局域网IP：3010，即可访问EasyAI应用

Windows 一键启动

start.ps1 脚本用于 Windows 本机/局域网一键部署 EasyAI 应用。不要直接双击运行（会闪退），请按以下方式执行：

权限配置（首次执行必做）

PowerShell 默认可能禁止运行脚本，需先执行以下任一方式：

方式一：临时允许本次运行（推荐）

powershell -ExecutionPolicy Bypass -File .\start.ps1

方式二：为当前用户永久放开脚本执行权限

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

执行后再运行 .\start.ps1 即可。

启动步骤

1. 克隆并进入目录

git clone https://git.51easyai.com/wangbo/easyai.git
cd easyai

2. 在 PowerShell 或 CMD 中运行（二选一）

# 若已设置 ExecutionPolicy，可直接执行
.\start.ps1

# 未设置时使用 Bypass 方式
powershell -ExecutionPolicy Bypass -File .\start.ps1

3. 按提示选择 [1] 本地访问 或 [2] 局域网访问，脚本将自动配置并启动 Docker 服务。

4. 若窗口闪退，可查看日志 start.ps1.log（与 start.ps1 同目录，或 %TEMP%\start.ps1.log）获取退出原因。

启用HTTPS

1. [更改为你的域名]修改easyai-proxy.conf中域名51easyai.com为你的域名[可以使用Ctrl+F批量替换51easyai.com为你的域名]
2. [修改.env文件]修改如下两个环境变量为如下的对应的值

NUXT_PUBLIC_BASE_APIURL=/api
NUXT_PUBLIC_BASE_SOCKETURL=wss://<你的域名>/socket.io

3. [首次执行，后续无需重复执行]添加执行权限，命令：

chmod +x https.sh

4. 启用HTTPS

./https.sh

配置PDF图文解析Markdown功能

如果需要启用PDF图文解析Markdown功能，需要env.tools中的OSS环境变量，具体参考文件中的配置说明：自动解析PDF图文，将图片文件上传到OSS，并解析成Markdown格式，并返回

更新升级

update.sh 脚本用于自动更新 EasyAI 应用，包含以下功能：

• 拉取整个仓库：执行 git pull 获取最新代码（docker-compose.yml、start.sh、.env.*.sample 等全部文件）
• 自动补齐缺失的环境配置文件（.env、.env.tools、.env.ASG、.env.AMS，从 .sample 生成且不覆盖已有文件）
• 兼容 docker compose 和 docker-compose 两种命令格式
• 自动拉取最新镜像并重启服务

使用步骤

1. [首次执行，后续无需重复执行]添加执行权限，命令：

chmod +x update.sh

2. 执行更新（默认会 git pull 拉取整个仓库）

./update.sh

注意：update.sh 需要在 Git 克隆的目录下运行。若通过 zip 下载而非 git clone，请先使用 git clone 获取项目。

使用方式

• 执行 ./update.sh 后会命令行内选择更新方式：

  • [1] 更新并拉取仓库（git pull）+ 更新镜像并重启（默认，回车即选）
  • [2] 仅更新镜像并重启（跳过 git pull，适用于有本地修改不想被覆盖的场景）

• 查看帮助：./update.sh -h 或 ./update.sh --help

更新说明

• 脚本会执行 git pull 拉取整个仓库最新代码
• 拉取后会检查并补齐缺失的 .env、.env.tools、.env.ASG、.env.AMS（不会覆盖已有文件）
• 最后执行 docker compose pull 和 docker compose up -d 拉取镜像并重启服务

Windows 用户（update.ps1）

Windows 下使用 update.ps1，功能与 Linux 版一致：

.\update.ps1

• 执行后会命令行内选择：[1] 更新并拉取仓库 + 更新镜像（默认）；[2] 仅更新镜像
• 需在 Git 克隆的 easyai 目录下运行

常见问题

1. 某个服务无法运行 解决方案：重启docker（可以解决99%的问题）

# 
cd easyai && docker compose down && docker compose up -d 
#如果提示docker "compose" is not a docker command,则使用下面的命令
cd easyai && docker-compose down && docker-compose up -d 

2. 启动时提示Error: listen EADDRINUSE: address already in use :::3000 端口占用，请检查端口3000是否被其他程序占用
3. invalid interpolation format for services.mongo.ports.[]. You may need to escape any with another 等关于docker-compose文件格式的报错 解决方案：docker-compose 版本太低，一般为服务器之前自己使用apt安装低版本的docker-compose，需要卸载重新安装

# 卸载docker-compose
apt remove docker-compose
#重新安装
./start.sh

4. 单独更新docker-compose.yml文件，并更新

cd ~/easyai && cp docker-compose.yml docker-compose.yml.backup && wget -q https://git.51easyai.com/wangbo/easyai/raw/main/docker-compose.yml -O docker-compose.yml && echo "✅ docker-compose.yml 更新完成"