文档/安装部署

安装部署指南

MyInc 网巢是一套分布式多智能体平台，用 Python 编写，前端基于 Vue 3。本文档指导你从零开始部署系统，支持 Docker 容器与直接 Python 两种安装方式，全程无需 Git，数据与程序完全解耦。

概述

MyInc 网巢的安装哲学可以概括为三条：

零 Git 依赖：所有发行版以 zip 形式分发，从官网直接下载。不需要 git clone，也不需要配置 SSH Key。
数据与代码分离：所有运行时数据（数据库、向量索引、上传文件、角色记忆）都存放在独立的 data/ 目录。升级程序只替换代码，不动 data/。
容器与直装等价：Docker Compose 和裸机 Python 两种方式功能完全相同，生产推荐容器，开发推荐直装。

关于技术栈 后端是纯 Python（FastAPI + asyncio + SQLAlchemy），前端是 Vue 3 + Vite。没有使用 Rust、没有编译步骤，Python 3.11+ 直接解释执行。

系统要求

最低配置

资源	最低	推荐	说明
CPU	2 核	4 核 +	Agent 并发越多核心要求越高
内存	4 GB	8 GB +	含 ChromaDB 向量索引 + 多 Agent 进程
硬盘	20 GB	100 GB +	日志和历史记忆会持续增长
操作系统	Linux / macOS / Windows（WSL2）		生产环境推荐 Linux

软件依赖

根据你选的安装方式，需要预先安装以下软件：

方式	必需	可选
Docker 安装	`Docker 24+` · `Docker Compose v2`	无
Python 直装	`Python 3.11+` · `Node.js 20+` · `Redis 7+`	`SQLite`（已内置）

下载安装包

所有发行版由官网直接提供下载链接，无需任何账号或 Git 凭证。

从官网下载最新版 BASH

# 下载最新稳定版（自动跳转到 releases CDN）
curl -L -o myinc.zip yulvetech.com/releases/latest.zip

# 或下载指定版本
curl -L -o myinc-v1.0.0.zip yulvetech.com/releases/v1.0.0.zip

# 解压到工作目录
unzip myinc.zip -d myinc/
cd myinc/

校验完整性 每个发行包都附带 SHA256SUMS 文件，强烈建议下载后校验： sha256sum -c SHA256SUMS

目录结构预览

解压后你会看到如下目录结构：

myinc/ TREE

myinc/
├── backend/              # Python 后端源码
├── frontend/             # Vue 3 前端源码（含 dist/ 预编译产物）
├── roles/                # 角色配置模板（*.toml）
├── skills/               # 技能目录（workspace / shared / builtin）
├── workflows/            # 工作流配置
├── data/                 # 【独立】运行时数据——升级时保留
│   ├── app.db           # 主数据库
│   ├── memory.db        # 记忆数据库
│   └── chroma/          # 向量索引
├── docker-compose.yml    # Docker 编排文件
├── pyproject.toml        # Python 依赖定义
├── .env.example          # 环境变量模板
└── Makefile              # 常用命令快捷方式

Docker 容器安装推荐

这是生产环境的推荐部署方式。所有服务都在容器内运行，数据通过 volume 挂载到宿主机 data/ 目录。

Docker 容器

一键启动全部服务，数据卷挂载，升级最简单。

生产推荐隔离性强升级快

Python 直装

直接跑在宿主机 Python 环境，调试方便。

开发友好依赖多

Step 1 · 复制环境变量模板

配置环境 BASH

cp .env.example .env
nano .env  # 或用你喜欢的编辑器

至少需要填以下几项（详见环境变量章节）：

.env DOTENV

# LLM 提供商密钥（至少填一个）
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxxxxxx

# JWT 签名密钥（首次启动请随机生成 32 字节字符串）
SECRET_KEY=请改成随机生成的 32 字节字符串

# 数据库 URL（默认 SQLite，无需改动）
DATABASE_URL=sqlite+aiosqlite:///data/app.db

# Redis（docker-compose 会自动起一个）
REDIS_URL=redis://redis:6379

# Telegram 通知（可选）
TELEGRAM_BOT_TOKEN=123456:ABC...
MANAGER_CHAT_ID=-100xxxxx

Step 2 · 启动容器

一键启动全部服务 BASH

# 前台启动（首次建议，方便看启动日志）
docker compose up

# 后台启动（生产推荐）
docker compose up -d

# 查看服务状态
docker compose ps

启动后 docker-compose.yml 会起以下服务：

服务名	作用	端口
`control`	Control Plane + Web API	`9001`
`frontend`	nginx 托管前端静态文件	`8080`
`redis`	任务队列 + 跨机通信	`6379`
`chroma`	向量数据库（server 模式）	`8000`
`agent-*`	每个 Agent 一个容器（按需）	-

端口冲突 如果 8080 / 9001 / 6379 在你机器上已被占用，编辑 docker-compose.yml 里的 ports 段改成空闲端口即可。

直接 Python 安装

适用于开发调试、单机小规模部署、或不方便用 Docker 的环境。

Step 1 · 创建虚拟环境

创建并激活 venv BASH

# 进入解压后的目录
cd myinc/

# 创建虚拟环境
python3.11 -m venv .venv

# 激活（Linux / macOS）
source .venv/bin/activate

# 激活（Windows PowerShell）
.venv\Scripts\Activate.ps1

Step 2 · 安装依赖

安装后端与前端依赖 BASH

# 安装 Python 后端依赖（含 dev 工具）
pip install -e ".[dev]"

# 安装 Playwright 浏览器（供浏览器自动化技能使用）
playwright install chromium

# 前端依赖（如果要自己构建；发行包已含 dist/）
cd frontend/
npm install
npm run build
cd ..

Step 3 · 启动 Redis（如果本地还没装）

Ubuntu / Debian BASH

sudo apt install redis-server
sudo systemctl start redis
sudo systemctl enable redis

Homebrew BASH

brew install redis
brew services start redis

Windows 推荐用 Docker 跑 Redis，或者用 WSL2 里的 Linux 安装方式。

Docker Desktop POWERSHELL

docker run -d --name myinc-redis -p 6379:6379 redis:7

Step 4 · 配置环境变量

同 Docker 方式，复制 .env.example 为 .env 并填写。

Step 5 · 初始化数据库

首次启动要做的初始化 BASH

# 初始化数据库 schema（幂等，重复执行无副作用）
python -m backend.cli.main db init

# 可选：导入示例数据
python -m backend.cli.main db seed

验证安装

无论用哪种方式，完成后都应该能访问以下地址：

地址	用途	预期响应
`http://localhost:8080`	Web 管理后台首页	登录页
`http://localhost:9001/api/health`	后端健康检查	`{"status":"ok"}`
`http://localhost:9001/docs`	API 文档（Swagger UI）	API 列表

命令行快速验证 BASH

# 检查后端健康
curl http://localhost:9001/api/health

# 期望输出：
# {"status":"ok","version":"1.0.0","db":"ok","redis":"ok"}

环境变量详解

所有配置通过 .env 文件注入，不要直接把密钥写在代码里。以下是完整的变量列表：

变量名	必填	默认值	说明
`ANTHROPIC_API_KEY`	任选一	-	Claude API 密钥
`OPENAI_API_KEY`	任选一	-	OpenAI API 密钥
`SECRET_KEY`	✓	-	JWT 签名密钥（32 字节随机）
`DATABASE_URL`	✗	`sqlite+aiosqlite:///data/app.db`	数据库连接字符串
`REDIS_URL`	✗	`redis://localhost:6379`	Redis 地址
`CHROMA_MODE`	✗	`embedded`	`embedded` / `server`
`CHROMA_HOST`	server 模式	`localhost`	ChromaDB 服务地址
`CHROMA_PORT`	server 模式	`8000`	ChromaDB 服务端口
`CONTROL_PLANE_URL`	跨机器时	`http://localhost:9001`	Control Plane 地址，Worker 向此注册
`TELEGRAM_BOT_TOKEN`	✗	-	Telegram 机器人 Token
`MANAGER_CHAT_ID`	✗	-	管理员 Telegram chat id
`STAFF_CHAT_ID`	✗	-	员工 Telegram 群组 chat id

生成 SECRET_KEY 不要使用示例里的字符串，务必自己随机生成一个：
python -c "import secrets; print(secrets.token_urlsafe(32))"

创建第一个 Agent

Agent（角色）通过 roles/ 目录下的 TOML 文件定义。以"录入员"为例：

roles/intake_clerk.toml TOML

[role]
id = "intake_clerk"
name = "录入员小王"
description = "接收订单邮件并录入 ERP"
enabled = true

[model]
provider = "anthropic"
model = "claude-haiku-4-5"
temperature = 0.3

[persona]
text = """
你是一个细心负责的录入员，擅长从邮件和 Excel 中识别订单信息。
发现歧义时先问清楚再执行。
"""

[schedule]
mode = "realtime"          # realtime / cron
channel = "inbox.intake"

[skills]
installed = ["validate", "erp_connector", "notify_parties"]

[permissions]
can_read_tables = ["orders", "products"]
can_write_tables = ["orders"]

[permissions.approval]
require_for_skills = ["erp_connector"]

[notifications]
telegram_chat_ids = ["$MANAGER_CHAT_ID"]

启动这个 Agent BASH

# CLI 启动（Python 直装方式）
python -m backend.bin.agent --role roles/intake_clerk.toml

# 或通过 CLI 工具统一管理
myinc roles start --role intake_clerk

# Docker 方式：在 docker-compose.yml 添加一个 service
# 然后：docker compose up -d agent-intake

配置通知渠道

Agent 向人推送审批请求、日报、告警的渠道。开箱即用的有 Telegram、Email、WebHook、CLI。

创建 Bot 在 Telegram 中找 @BotFather，发送 /newbot，按提示创建。拿到 Token 后填入 TELEGRAM_BOT_TOKEN。
获取 Chat ID 把 Bot 拉进你的群组，发一条消息，然后访问：
https://api.telegram.org/bot<TOKEN>/getUpdates
在返回的 JSON 里找 chat.id，填入 MANAGER_CHAT_ID。
在 role.toml 引用 telegram_chat_ids = ["$MANAGER_CHAT_ID"]（以 $ 开头表示读取环境变量）。

启动服务

Docker Compose 常用命令 BASH

# 启动全部
docker compose up -d

# 只启动某个服务
docker compose up -d control frontend redis

# 查看实时日志
docker compose logs -f control

# 重启某个服务
docker compose restart control

# 停止全部
docker compose down

# 停止并清理网络（不删 volume，data/ 安全）
docker compose down --remove-orphans

Python 进程管理 BASH

# 启动 Control Plane（Web UI + API）
python -m backend.bin.control

# 另开终端，启动一个 Agent Worker
python -m backend.bin.agent --role roles/intake_clerk.toml

# 生产环境建议用 systemd 或 supervisor 管理进程
# 示例 systemd unit 见 docs/deployment.md

当 Agent 需要部署到多台机器（如边缘设备 + 云服务器）时：

跨机器架构 BASH

#【主机】启动 Control Plane
python -m backend.bin.control

#【子机】启动 Agent Worker，指向主机的 Control Plane
CONTROL_PLANE_URL=http://主机IP:9001 \
  python -m backend.bin.agent --role roles/fire_inspector.toml

# Redis 需要配置成主机可被子机访问
# 推荐在主机启动时绑定到 0.0.0.0 并配置密码

命令行工具

安装后可使用 myinc 命令（Python 直装）或 docker compose exec control myinc（容器内）。

命令	作用
`myinc roles list`	列出所有角色及状态
`myinc roles start --role <name>`	启动角色
`myinc roles stop --role <name>`	停止角色
`myinc skills install <zip-path>`	从 zip 安装技能
`myinc skills list`	列出已安装技能
`myinc memory list --role <name>`	查看角色记忆
`myinc memory export --role <name> --out backup.json`	导出记忆
`myinc workflows trigger <name>`	手动触发工作流

Web 管理后台

访问 http://localhost:8080（或你配置的域名）。首次登录：

默认用户名	`admin`
默认密码	`admin`（登录后立即修改）

Web 后台提供：

实时看板 — 所有角色的状态、任务流、跨角色调用图
角色管理 — 在线编辑 TOML、启动 / 停止、直接对话
工作流编排 — 拖拽式流程设计器
记忆管理 — 六层记忆分标签页浏览、搜索、删除
审批队列 — 待审批事项一键通过 / 拒绝 / 修改
拓扑视图 — 分布式节点状态

备份数据

数据与代码完全分离

程序代码和运行数据是两个独立维度。升级代码不影响数据，备份数据不需要备份代码。

代码：backend/ · frontend/ · roles/ · skills/（全部来自发行包）
数据：data/ 目录（包含所有数据库和记忆）
配置：.env 文件（密钥和连接串）

定期备份 data/ 目录

全量备份脚本 BASH

# 停止服务（避免备份时数据库在写）
docker compose stop
# 或 Python 方式：停止所有 python -m backend.bin.* 进程

# 打包 data/ 和 .env
BACKUP_NAME="myinc-backup-$(date +%Y%m%d-%H%M%S).tar.gz"
tar czf "$BACKUP_NAME" data/ .env roles/

# 重启服务
docker compose start

echo "备份完成: $BACKUP_NAME"

自动备份建议 加到 crontab：0 2 * * * cd /opt/myinc && ./scripts/backup.sh
每天凌晨 2 点自动备份，然后 rsync 到异地存储。

逻辑备份（仅记忆）

导出指定角色的记忆 BASH

# 导出单个角色的所有记忆（JSON 格式）
myinc memory export --role intake_clerk --out intake_memory.json

# 恢复到另一个实例
myinc memory import --role intake_clerk --in intake_memory.json

升级程序

升级的核心原则：只替换代码目录，保留 data/ 和 .env。

备份当前数据 按上节方法打包 data/ 和 .env。这是唯一真正重要的步骤。
下载新版 zip curl -L -o myinc-new.zip yulvetech.com/releases/latest.zip
停止现有服务 docker compose down（或停止 Python 进程）
保留 data/ 和 .env，替换其他文件 见下方脚本。
运行数据库迁移 myinc db migrate（幂等，不会动已有数据）
重启服务 docker compose up -d
验证版本 curl http://localhost:9001/api/health 确认返回新版本号。

安全升级脚本 BASH

#!/usr/bin/env bash
# 安全升级：保护 data/ 和 .env 绝对不被覆盖

set -euo pipefail

INSTALL_DIR="/opt/myinc"
NEW_ZIP="$1"            # 例: myinc-v1.1.0.zip
TS=$(date +%Y%m%d-%H%M%S)

cd "$INSTALL_DIR"

# 1. 备份 data/ 和 .env
echo "[1/6] 备份 data/ 和 .env ..."
tar czf "../backup-$TS.tar.gz" data/ .env

# 2. 停止服务
echo "[2/6] 停止服务 ..."
docker compose down

# 3. 保存当前版本到 old/ 以备回滚
echo "[3/6] 备份当前代码 ..."
mkdir -p ../old
mv "$INSTALL_DIR" "../old/myinc-$TS"

# 4. 解压新版到原路径
echo "[4/6] 解压新版本 ..."
mkdir -p "$INSTALL_DIR"
unzip -q "$NEW_ZIP" -d "$INSTALL_DIR"

# 5. 把 data/ 和 .env 从备份恢复回来
echo "[5/6] 恢复数据和配置 ..."
cd "$INSTALL_DIR"
tar xzf "../backup-$TS.tar.gz"

# 6. 迁移数据库 + 重启
echo "[6/6] 迁移数据库 + 重启 ..."
docker compose run --rm control myinc db migrate
docker compose up -d

echo "✓ 升级完成"

重要：永远不要直接把新 zip 解压到原目录 解压工具会覆盖同名文件但不会删除你自定义的文件，长期使用会累积孤儿文件。建议严格按上面脚本：新版解压到新路径 → data/.env 从备份还原。

回滚版本

如果升级后出问题，3 分钟内可完全回滚：

回滚到上个版本 BASH

set -euo pipefail

INSTALL_DIR="/opt/myinc"
OLD_VER="$1"               # 例: myinc-20260420-143000

cd "$INSTALL_DIR"

# 停止当前服务
docker compose down

# 保留当前 data/ 和 .env
tar czf "../preserve-$(date +%s).tar.gz" data/ .env

# 恢复旧版本代码
rm -rf "$INSTALL_DIR"
mv "../old/$OLD_VER" "$INSTALL_DIR"

# 启动
cd "$INSTALL_DIR"
docker compose up -d

echo "✓ 已回滚到 $OLD_VER"

回滚的数据库注意事项 如果新版本执行过数据库 migrate 且引入了不可逆变更（如删列），回滚代码后数据库 schema 可能与旧代码不兼容。这种情况下需要从升级前的备份完整恢复 data/app.db。

查看日志

容器日志BASH

# 实时跟踪全部服务
docker compose logs -f

# 只看某个服务
docker compose logs -f control
docker compose logs -f agent-intake

# 最后 100 行
docker compose logs --tail=100 control

直装方式下，日志写到 data/logs/ 目录：

文件日志BASH

tail -f data/logs/control.log
tail -f data/logs/agent-intake_clerk.log

常见问题

启动时报 "Address already in use"

端口被占用。找到占用进程并关闭，或修改 docker-compose.yml 的端口映射：

查找占用端口的进程BASH

# Linux / macOS
lsof -i :9001
kill -9 <PID>

# Windows
netstat -ano | findstr :9001
taskkill /PID <PID> /F

Agent 启动后 5 秒就退出

99% 是 .env 里的 API Key 没配或无效。检查：

ANTHROPIC_API_KEY 或 OPENAI_API_KEY 至少填一个
Key 前后没有多余空格 / 引号
日志里是否有 401 Unauthorized

升级后 Web UI 打不开

浏览器缓存所致。强制刷新（Ctrl+Shift+R）或清空缓存。

记忆查询返回空

检查 ChromaDB 是否正常运行：

ChromaDB 健康检查BASH

# server 模式
curl http://localhost:8000/api/v1/heartbeat

# embedded 模式 · 确认 data/chroma/ 目录可读可写
ls -la data/chroma/

Redis 连不上

容器方式下 REDIS_URL 应该是 redis://redis:6379（用容器名而不是 localhost）。直装方式是 redis://localhost:6379。

卸载

卸载前请先备份 data/ 目录！ 卸载后 data/ 里所有数据库、记忆、对话历史将无法恢复。

完整卸载流程BASH

# 1. 备份（非常重要）
tar czf "~/myinc-final-backup.tar.gz" data/ .env

# 2. 停止并删除容器
docker compose down -v    # -v 会删除 volume

# 3. 删除安装目录
cd ..
rm -rf myinc/

# 4. 如果用了 Python 直装，还要删虚拟环境
rm -rf .venv/

# 5. 清理 Docker 镜像（可选）
docker image prune -a

安装部署指南

概述

系统要求

最低配置

软件依赖

下载安装包

目录结构预览

Docker 容器安装 推荐

Docker 容器

Python 直装

Step 1 · 复制环境变量模板

Step 2 · 启动容器

直接 Python 安装

Step 1 · 创建虚拟环境

Step 2 · 安装依赖

Step 3 · 启动 Redis（如果本地还没装）

Step 4 · 配置环境变量

Step 5 · 初始化数据库

验证安装

环境变量详解

创建第一个 Agent

配置通知渠道

Telegram

启动服务

命令行工具

Web 管理后台

备份数据

数据与代码完全分离

定期备份 data/ 目录

逻辑备份（仅记忆）

升级程序

回滚版本

查看日志

常见问题

启动时报 "Address already in use"

Agent 启动后 5 秒就退出

升级后 Web UI 打不开

记忆查询返回空

Redis 连不上

卸载

Docker 容器安装推荐