wuyang/zk-data-agent

Fork 0

Files

T

武阳 d42e024ccd Support optional Ubuntu system bootstrap

2026-05-07 12:05:41 +08:00

5.4 KiB

Raw Blame History

ZK Data Agent

ZK Data Agent 是面向中控数据开发流程的 Agent 服务。当前仓库包含：

Python 后端：负责 Agent loop、工具调用、会话持久化和数据开发工具。
Next.js 前端：提供 Web UI、会话管理、工具调用展示和数据开发交互入口。
Skill / Tools：承载产品定义到数据生成、线上数据挖掘等数据开发链路。

快速部署

从 Git 一键部署

适合首次部署，也适合后续更新：

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
'

如果是全新 Ubuntu 机器，也可以在同一个入口中打开系统依赖初始化：

BOOTSTRAP_SYSTEM=1 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
'

修改部署目录或分支时，只需要调整命令开头的变量：

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 scripts/deploy-ubuntu.sh

如果是全新 Ubuntu 机器，首次安装可以让脚本顺手安装系统依赖：

bash scripts/deploy-ubuntu.sh --bootstrap-system

--bootstrap-system 会使用 sudo apt-get 安装 Python 编译依赖、git、curl 等系统包；应用代码、.venv、前端依赖、运行数据和 systemd 用户服务仍然都在当前用户目录下。

部署指定分支：

bash scripts/deploy-ubuntu.sh main

强制覆盖服务器工作区：

bash scripts/deploy-ubuntu.sh main --force

部署配置

首次执行 scripts/deploy-ubuntu.sh 时，如果仓库根目录不存在 .env.deploy，脚本会交互式提示输入：

OPENAI_API_KEY
OPENAI_BASE_URL
OPENAI_MODEL
后端监听地址和端口
前端监听地址和端口

配置会写入：

.env.deploy

该文件包含敏感信息，只保存在部署机器本地，权限会设置为 600，并且已被 .gitignore 忽略，不会提交到 git。

如需修改模型或 key：

vim .env.deploy

可参考示例：

cp .env.deploy.example .env.deploy

运行方式

部署脚本会安装两个用户级 systemd 服务，不需要 sudo：

zk-data-agent-backend
zk-data-agent-frontend

查看状态：

systemctl --user status zk-data-agent-backend
systemctl --user status zk-data-agent-frontend

查看日志：

journalctl --user -u zk-data-agent-backend -f
journalctl --user -u zk-data-agent-frontend -f

重启服务：

systemctl --user restart zk-data-agent-backend zk-data-agent-frontend

停止服务：

systemctl --user stop zk-data-agent-backend zk-data-agent-frontend

本地开发启动

本地调试可以使用：

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 后仍保持运行，可由管理员额外执行：

loginctl enable-linger <username>

目录说明

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 只用于本地调试。

5.4 KiB Raw Blame History Unescape Escape