武阳
220 lines
5.5 KiB
Markdown
220 lines
5.5 KiB
Markdown
# ZK Data Agent
|
||
|
||
ZK Data Agent 是面向中控数据开发流程的 Agent 服务。当前仓库包含：
|
||
|
||
- Python 后端：负责 Agent loop、工具调用、会话持久化和数据开发工具。
|
||
- Next.js 前端：提供 Web UI、会话管理、工具调用展示和数据开发交互入口。
|
||
- Skill / Tools：承载产品定义到数据生成、线上数据挖掘等数据开发链路。
|
||
|
||
## 快速部署
|
||
|
||
### 从 Git 一键部署
|
||
|
||
适合首次部署。该命令会在拉取代码后执行 `--bootstrap-system`，必要时使用 sudo 安装 Ubuntu 系统依赖；应用本身仍部署在用户目录。
|
||
|
||
```bash
|
||
APP_DIR="$HOME/zk-data-agent" BRANCH="main" REPO="git@git.n.xiaomi.com:wuyang6/zk-data-agent.git" bash -lc '
|
||
set -euo pipefail
|
||
|
||
if [ -d "$APP_DIR/.git" ]; then
|
||
cd "$APP_DIR"
|
||
git fetch origin
|
||
git checkout "$BRANCH"
|
||
git pull --ff-only origin "$BRANCH"
|
||
else
|
||
rm -rf "$APP_DIR"
|
||
git clone --branch "$BRANCH" "$REPO" "$APP_DIR"
|
||
cd "$APP_DIR"
|
||
fi
|
||
|
||
bash scripts/deploy-ubuntu.sh "$BRANCH" --skip-git --bootstrap-system
|
||
'
|
||
```
|
||
|
||
后续更新不需要安装系统依赖，可以使用：
|
||
|
||
```bash
|
||
APP_DIR="$HOME/zk-data-agent" BRANCH="main" REPO="git@git.n.xiaomi.com:wuyang6/zk-data-agent.git" bash -lc '
|
||
set -euo pipefail
|
||
|
||
if [ -d "$APP_DIR/.git" ]; then
|
||
cd "$APP_DIR"
|
||
git fetch origin
|
||
git checkout "$BRANCH"
|
||
git pull --ff-only origin "$BRANCH"
|
||
else
|
||
rm -rf "$APP_DIR"
|
||
git clone --branch "$BRANCH" "$REPO" "$APP_DIR"
|
||
cd "$APP_DIR"
|
||
fi
|
||
|
||
bash scripts/deploy-ubuntu.sh "$BRANCH" --skip-git
|
||
'
|
||
```
|
||
|
||
修改部署目录或分支时，只需要调整命令开头的变量：
|
||
|
||
```bash
|
||
APP_DIR="$HOME/zk-data-agent-test" BRANCH="main" REPO="git@git.n.xiaomi.com:wuyang6/zk-data-agent.git" bash -lc '...'
|
||
```
|
||
|
||
这个命令会自动完成：
|
||
|
||
- 目标目录不存在时执行 `git clone`
|
||
- 目标目录已存在时执行 `git fetch` / `git pull --ff-only`
|
||
- 进入仓库后执行 `bash scripts/deploy-ubuntu.sh`
|
||
|
||
说明：仓库是私有仓库，`curl | bash` 拉 raw 文件时容易拿到登录页 HTML；因此推荐直接走 SSH git 权限。
|
||
|
||
### 仓库内一键部署/更新
|
||
|
||
如果已经在仓库目录中，日常更新直接执行：
|
||
|
||
```bash
|
||
bash scripts/deploy-ubuntu.sh
|
||
```
|
||
|
||
如果是全新 Ubuntu 机器，首次安装可以让脚本顺手安装系统依赖：
|
||
|
||
```bash
|
||
bash scripts/deploy-ubuntu.sh --bootstrap-system
|
||
```
|
||
|
||
`--bootstrap-system` 会使用 `sudo apt-get` 安装 Python 编译依赖、`git`、`curl` 等系统包；应用代码、`.venv`、前端依赖、运行数据和 systemd 用户服务仍然都在当前用户目录下。
|
||
|
||
部署指定分支：
|
||
|
||
```bash
|
||
bash scripts/deploy-ubuntu.sh main
|
||
```
|
||
|
||
强制覆盖服务器工作区：
|
||
|
||
```bash
|
||
bash scripts/deploy-ubuntu.sh main --force
|
||
```
|
||
|
||
## 部署配置
|
||
|
||
首次执行 `scripts/deploy-ubuntu.sh` 时，如果仓库根目录不存在 `.env.deploy`，脚本会交互式提示输入：
|
||
|
||
- `OPENAI_API_KEY`
|
||
- `OPENAI_BASE_URL`
|
||
- `OPENAI_MODEL`
|
||
- 后端监听地址和端口
|
||
- 前端监听地址和端口
|
||
|
||
配置会写入：
|
||
|
||
```text
|
||
.env.deploy
|
||
```
|
||
|
||
该文件包含敏感信息，只保存在部署机器本地，权限会设置为 `600`，并且已被 `.gitignore` 忽略，不会提交到 git。
|
||
|
||
如需修改模型或 key：
|
||
|
||
```bash
|
||
vim .env.deploy
|
||
```
|
||
|
||
可参考示例：
|
||
|
||
```bash
|
||
cp .env.deploy.example .env.deploy
|
||
```
|
||
|
||
## 运行方式
|
||
|
||
部署脚本会安装两个用户级 systemd 服务，不需要 sudo：
|
||
|
||
```bash
|
||
zk-data-agent-backend
|
||
zk-data-agent-frontend
|
||
```
|
||
|
||
查看状态：
|
||
|
||
```bash
|
||
systemctl --user status zk-data-agent-backend
|
||
systemctl --user status zk-data-agent-frontend
|
||
```
|
||
|
||
查看日志：
|
||
|
||
```bash
|
||
journalctl --user -u zk-data-agent-backend -f
|
||
journalctl --user -u zk-data-agent-frontend -f
|
||
```
|
||
|
||
重启服务：
|
||
|
||
```bash
|
||
systemctl --user restart zk-data-agent-backend zk-data-agent-frontend
|
||
```
|
||
|
||
停止服务：
|
||
|
||
```bash
|
||
systemctl --user stop zk-data-agent-backend zk-data-agent-frontend
|
||
```
|
||
|
||
## 本地开发启动
|
||
|
||
本地调试可以使用：
|
||
|
||
```bash
|
||
bash scripts/start-webui.sh
|
||
```
|
||
|
||
默认端口：
|
||
|
||
- 前端：`http://127.0.0.1:3000`
|
||
- 后端：`http://127.0.0.1:8765`
|
||
|
||
`scripts/start-webui.sh` 会优先读取本机 `.env.deploy`，也可以直接使用当前 shell 中的环境变量。
|
||
|
||
## 环境要求
|
||
|
||
Ubuntu 部署建议准备：
|
||
|
||
- `git`
|
||
- `bash`
|
||
- `curl`
|
||
- `systemd`
|
||
- `pyenv`
|
||
- Python `3.10.14`
|
||
- Node.js `20` 或 `22`
|
||
- `npm`
|
||
|
||
如果机器缺少 Python 编译依赖，首次执行时可加 `--bootstrap-system`，脚本会请求 sudo 安装系统包。日常部署和更新不需要 sudo。
|
||
|
||
Python 后端依赖由部署脚本安装到项目根目录 `.venv`。
|
||
|
||
前端依赖由部署脚本在 `frontend/app` 下执行 `npm ci` 安装，并执行 `npm run build`。
|
||
|
||
默认部署使用用户级 systemd，不需要 sudo。若机器要求服务在用户退出 SSH 后仍保持运行，可由管理员额外执行：
|
||
|
||
```bash
|
||
loginctl enable-linger <username>
|
||
```
|
||
|
||
## 目录说明
|
||
|
||
```text
|
||
backend/ FastAPI Web 后端
|
||
frontend/app/ Next.js 前端
|
||
src/ Agent runtime、tools、skills
|
||
scripts/ 本地启动、部署、systemd 启动脚本
|
||
deploy/systemd/ systemd service 模板
|
||
.port_sessions/ 本地运行数据，禁止提交
|
||
.env.deploy 本机私有部署配置，禁止提交
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
- 不要把 `OPENAI_API_KEY` 写入可提交文件。
|
||
- `.env.deploy`、`.venv`、`.port_sessions` 都是本机文件，不进入 git。
|
||
- 服务器更新优先使用 `bash scripts/deploy-ubuntu.sh`，不要手工分散执行依赖安装和服务重启。
|
||
- 生产/长期运行使用 systemd 服务；`scripts/start-webui.sh` 只用于本地调试。
|