开始使用
安装与启动
选择桌面客户端或 Docker，在本机启动完整 SAG 工作台。更新于 2026-07-22适用于 SAG v1.2.2
SAG 提供桌面客户端和 Docker 自托管两条安装路径。桌面版适合个人直接使用；Docker 适合开发、局域网或需要自行管理数据的环境。
选择安装方式
| 方式 | 适合谁 | 运行依赖 | 数据位置 |
|---|---|---|---|
| Desktop | 想开箱即用的个人用户 | 无需单独安装 Python、Node 或数据库 | 系统应用数据目录 |
| Docker Compose | 开发者、服务器与受信局域网 | Docker Desktop 或 Compose v2 | Docker volume sagdata |
| 本地源码 | 参与开发或调试前后端 | Python 3.11+、Node 20+ | apps/api/.data/ |
桌面客户端
从 GitHub Releases 下载最新稳定版本。
| 平台 | 安装文件 | 说明 |
|---|---|---|
| macOS 15+，Apple Silicon | SAG-*-mac-arm64.dmg | 已签名、公证，支持稳定通道自动更新 |
| Windows 10/11，x64 | SAG-Setup-*-win-x64.exe | 当前未签名，可能显示“未知发布者”，仍支持自动更新 |
每个 Release 同时发布 SHA256SUMS.txt，可以用它校验下载完整性。整包升级不会覆盖知识库与上传文件。
Docker 快速启动
git clone https://github.com/Zleap-AI/SAG.git
cd SAG
docker compose up -d --build首次启动无需 API Key、Python、Node 或外部数据库。两个服务健康后打开：
- Web 工作台：
http://localhost:3000 - OpenAPI 文档：
http://localhost:8000/docs - API 就绪检查：
http://localhost:8000/api/v1/system/ready
查看服务状态：
docker compose ps
docker compose logs -f api webapi 与 web 都应显示为 healthy。首轮镜像构建和 API 冷启动可能需要数分钟。
停止与再次启动
docker compose down
docker compose up -ddocker compose down 会停止容器，但保留 sagdata 中的数据库、知识索引和上传文件。
不要在仍需数据时运行
docker compose down -v。-v会永久删除默认数据卷。
自定义端口
复制环境变量模板后修改端口和浏览器访问的 API 地址：
cp .env.example .envWEB_PORT=3100
API_PORT=8100
BIND_ADDRESS=127.0.0.1
SAG_CORS_ORIGINS=http://localhost:3100
NEXT_PUBLIC_API_BASE=http://localhost:8100NEXT_PUBLIC_API_BASE 会写入 Web 构建产物，修改后需要重新构建：
docker compose up -d --build网络边界
默认 Compose 只监听 127.0.0.1。SAG 当前按本地单用户产品设计，不应直接把 3000 与 8000 端口暴露到公网。
需要远程访问时，请在前面增加 HTTPS 和外部访问控制，例如 VPN、IP 白名单或带认证的反向代理。完整要求见生产部署。
发现内容问题？以当前公开仓库为准。查看 SAG 源码