easyai/README.md

## 一键部署

### Linux

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

### Windows

```powershell
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`

---

## 更新升级
### 老客户（旧版本部署包）升级教程

如果你当前使用的是较早版本的部署包，**无法在旧包目录里直接执行 `git pull`** 来获取配置文件，建议按下面流程升级：

1. 先停止并下线旧项目容器：
```bash
cd ~/easyai
docker compose down
```
如果你的环境使用的是旧命令，请改用：
```bash
docker-compose down
```

2. 将旧目录重命名备份（示例改名为 `easyai2`）：
```bash
cd ~
mv easyai easyai2
```

3. 重新执行一键部署命令，按脚本提示完成初始化输入。

4. 当脚本询问是否启用 HTTPS 时：
   - 如果你之前已经有可用证书，填写 `N`（不生成新证书）。
   - 只有在需要新申请证书时，才选择启用并生成证书。

5. 完成上述迁移后，后续若有新的配置文件或版本更新，可直接在新的 `easyai` 目录中执行 `./update.sh` 进行更新。

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. [首次执行，后续无需重复执行]添加执行权限，命令：
```bash
chmod +x update.sh
```

2. 执行更新（默认会 `git pull` 拉取整个仓库）
```bash
./update.sh
```

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

### 使用方式
- 执行 `./update.sh` 后会**命令行内选择**更新方式：
  - `[1]` 更新并拉取仓库（git pull）+ 更新镜像并重启（**默认**，回车即选）
  - `[2]` 仅更新镜像并重启（跳过 git pull，适用于有本地修改不想被覆盖的场景）
- 如果本次**不涉及配置文件更新**（如 `.env*`、`docker-compose.yml`、`easyai-proxy.conf*` 无变更），可直接选择 `[2]`，仅更新后台服务镜像并重启即可。

- **查看帮助**：`./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 版一致：
```powershell
.\update.ps1
```
- 执行后会**命令行内选择**：`[1]` 更新并拉取仓库 + 更新镜像（默认）；`[2]` 仅更新镜像
- 需在 Git 克隆的 easyai 目录下运行

---

## 重要更新记录：

### 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`**

```bash
cp .env.AMS.sample .env.AMS
```

根据实际环境修改 `.env.AMS` 中的关键配置：
```dotenv
# 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，需显式启用：

```bash
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` 卷。

**步骤四：验证**

```bash
# 检查容器状态
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 地址：
```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-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`：
```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-pgvector`（PostgreSQL）和 `easyai-asg`（Agent 服务治理），数据库会在首次启动时自动完成初始化和迁移。

**步骤五：验证**

```bash
# 检查容器状态
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. 增加环境变量配置
```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参数的配置

## 其他功能配置

其他各项需要的功能配置可以自行查阅环境变量中的配置说明，下面是一些比较常用的功能配置

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


## 常见问题

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
```