easyai/README.md

## 重要更新记录：


### 2026.3.2

1. **新增 Agent 服务治理（ASG）模块**：新增 `easyai-asg`（Agent 服务治理）容器和独立的 `easyai-asg-pg`（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 地址：
```dotenv
# IP 直接访问方式
NUXT_PUBLIC_SG_APIURL=http://<你的服务器IP>:3003
# 域名 + Nginx 代理方式（需要配置步骤三的 Nginx 代理）
#NUXT_PUBLIC_SG_APIURL=/asg-api
```

**步骤二：配置 `.env.ASG`**

```bash
cp .env.ASG.sample .env.ASG
```

根据实际环境修改 `.env.ASG` 中的关键配置：
```dotenv
# PostgreSQL 连接（默认使用容器内网地址，一般无需修改）
ASG_DATABASE_URL=postgresql://easyai:easyai2025@easyai-asg-pg: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`：
```nginx
    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：
```bash
nginx -t && nginx -s reload
```

**步骤四：启动服务**

```bash
cd ~/easyai
docker compose up -d
```

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

**步骤五：验证**

```bash
# 检查容器状态
docker compose ps easyai-asg-pg 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. 增加环境变量配置
```dotenv
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`
```nginx configuration
    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和密码为实际的用户名和密码）
```bash
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. 克隆脚本和相关文件到服务器
```bash
git clone https://git.51easyai.com/wangbo/easyai.git
# 进入easyai目录
cd easyai
```

2. 去掉所有文件后缀的.sample后缀，修改env中环境变量，将下面两个环境变量修改为你的服务器的公网ip，本地局域网方式使用局域网IP
```bash
NUXT_PUBLIC_BASE_APIURL=http://<你的服务器公网IP或者局域网地址>:3001
NUXT_PUBLIC_BASE_SOCKETURL=ws://<你的服务器公网IP或者局域网地址>:3002
```
3. 开放服务器的3001、3002和3010端口
4. [首次执行，后续无需重复执行]添加脚本的执行权限，命令：
```bash
chmod +x start.sh
```
5. 执行start.sh脚本，即可自动安装依赖和启动EasyAI应用
```bash
./start.sh
```
6. 脚本运行完成无错误，并且提示`EasyAI应用启动成功`表示应用启动成功，打开浏览器输入服务器的公网ip：3010或者局域网IP：3010，即可访问EasyAI应用

## Windows 一键启动

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

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

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

**方式一：临时允许本次运行（推荐）**
```powershell
powershell -ExecutionPolicy Bypass -File .\start.ps1
```

**方式二：为当前用户永久放开脚本执行权限**
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```
执行后再运行 `.\start.ps1` 即可。

### 启动步骤

1. 克隆并进入目录
```powershell
git clone https://git.51easyai.com/wangbo/easyai.git
cd easyai
```

2. 在 PowerShell 或 CMD 中运行（二选一）
```powershell
# 若已设置 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文件]修改如下两个环境变量为如下的对应的值
```bash
NUXT_PUBLIC_BASE_APIURL=/api
NUXT_PUBLIC_BASE_SOCKETURL=wss://<你的域名>/socket.io
```
3. [首次执行，后续无需重复执行]添加执行权限，命令：
```bash
chmod +x https.sh
```
4. 启用HTTPS
```bash
./https.sh
```

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


### 更新升级
update.sh 脚本用于自动更新 EasyAI 应用，包含以下功能：
- 自动检查和更新 `docker-compose.yml` 文件（从远程仓库获取最新版本）
- 兼容 `docker compose` 和 `docker-compose` 两种命令格式
- 自动拉取最新镜像并重启服务

#### 使用步骤
1. [首次执行，后续无需重复执行]添加执行权限，命令：
```bash
chmod +x update.sh
```

2. 执行更新（默认会检查并更新 docker-compose.yml）
```bash
./update.sh
```

#### 参数选项
- **跳过 docker-compose.yml 更新**：如果你已经手动修改了 `docker-compose.yml` 文件，可以使用 `-s` 或 `--skip-compose-update` 参数跳过更新
```bash
# 跳过 docker-compose.yml 更新，仅更新容器镜像
./update.sh -s
# 或
./update.sh --skip-compose-update
```

- **查看帮助信息**：
```bash
./update.sh -h
# 或
./update.sh --help
```

#### 更新说明
- 脚本会自动从远程仓库下载最新的 `docker-compose.yml` 文件
- 如果本地文件与远程文件不同，会将原文件备份为 `docker-compose.yml.bak`
- 如果本地文件已是最新版本，则跳过更新
- 更新完成后会自动执行 `docker-compose pull` 和 `docker-compose up -d` 来重启服务





## 常见问题

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

```bash
# 
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，需要卸载重新安装
```bash
# 卸载docker-compose
apt remove docker-compose
#重新安装
./start.sh
```

4. 单独更新docker-compose.yml文件，并更新
```bash
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 更新完成"
```