语言

English 简体中文

Server v2

环境要求

Python 3.12+、MySQL 和 Node.js 22.12+。先完成源码环境安装。Redis 已不是 Server v2 的启动依赖。

启动

在仓库根目录、已激活 Python 环境的终端中运行：

python -m pip install -e '.[server-v2]'
cp app/v2/server/.env.example app/v2/server/.env

在 app/v2/server/.env 中配置 SAGE_SERVER_MYSQL_URL、自己的 SAGE_SERVER_JWT_SECRET（至少 32 字节），以及初始管理员账号。

cd app/v2/server/web
npm install
npm run build
cd ../../..
python -m app.v2.server

打开 http://127.0.0.1:8090，登录后配置模型和 Agent。/studio 管理 Agent 包，/docs 提供当前服务的 OpenAPI。

开发前端时，在 app/v2/server/web 中运行 npm run dev，Vite 代理到 8090 端口。进程环境变量优先于组件 .env 文件。

启动时幂等升级旧表：补齐缺失的 threads.agent_id，将 Skill 描述扩展为 LONGTEXT。数据库账号需要相应的 ALTER 权限。以前已截断的目录描述可重新导入原 Skill 文件修复。

存储与部署边界

• MySQL 保存用户、catalog、thread 索引、Agent 包库存和运行时 Session。
• AG-UI 回放直接读取 Sage Session 的权威 RuntimeEvent，不依赖另一份 Redis 事件日志。
• 工作区文件保存在配置的数据根目录下，按租户分隔。
• 使用单 worker。内置 SessionStore 拒绝第二个 writer；Scheduler 和 JobRuntime 不提供多宿主持久运行保证。

deploy/ 包含多套部署配置，使用前应核对具体环境的镜像和启动模块，不能将所有 Compose 环境都视作 Server v2。

环境变量 · HTTP API · 组件参考