← Discover MCPs and Agents
n
AgentAI & MLGitHub

nanzi-ai-agent-platform

🚀 开源企业级多智能体平台与 ChatBI 数据洞察平台。支持多 Agent 协作、RAG 知识增强、物理数据源直连与安全沙箱执行、Redis 长期记忆引擎，并集成多模态 EmbedChat 挂件与全方位 Token 消耗审计看板，完整 RBAC权限控制和 Harness支持。

Links

Repository

README

From the repo.

项目声明 本项目为个人开源，供自由学习交流，遵循 MIT 开源协议，可自由分发。 原项目名称「云枢」与其他企业项目重名，为避免混淆，现更名为「NanZi」。 「NanZi」来自我一直使用的网名（南孜），取「孜孜不倦」之意，寓意 AI 持续学习与进化。

NanZi · 智能体平台 (NanZi AI Agent Platform)

简体中文 | English

企业级 AI 智能体编排与执行平台 Connect Data. Orchestrate Intelligence.

Python AgentScope FastAPI Vue TailwindCSS ClickHouse Redis MCP License

📖 实战连载：NanZi 开源智能体平台实战连载（架构 · 安装 · 智能体配置 · ChatBI · 工具箱 · MCP）

❓ 疑难解答：疑难解答与常见问题手册 (FAQ)

Promo Overview

NanZi 智能体平台 是专为企业级复杂场景打造的 AI 智能中枢。

平台核心聚焦于以下能力矩阵：

  • 💬 深度交互式对话 (Dialogue & Co-Agent)：极速流式响应，支持 智能委派（默认进入 Main） 与 专家模式 / @提及直选、多专家协同。内置 工具预检 促发模型主动调用工具；支持 ask_user_question 智能提问卡（单选/多选/输入）、Todo 任务清单 分步执行与常驻跟踪；主助手支持 Skill 自动扫描 与权限挂起恢复。
  • 🛡️ 多策略安全沙箱与隔离执行 (Multi-Policy Sandbox)：原生支持 Local（本机进程）、Docker（私有容器隔离）、K8s（Kubernetes 原生 Pod 沙箱，云原生免 Docker Socket 安全推荐）、E2B（云端安全沙箱）、SSH（远端安全通道）五大执行策略；Docker 与 K8s 模式支持用户工作区同路径/subPath 挂载，支持在代码画布中直接打开预览并保存回物理文件；支持镜像预构建、空闲 30 分钟自动回收（Idle Reaper）、优雅停机清理及输入框浮标面板一键探测与秒级运行时长监控。
  • 🌐 持久化浏览器会话与实时接管面板 (Persistent Browser & Live Takeover)：服务端持久化浏览器会话与全套自动化工具（网页访问、点击、输入、拟人滑块轨迹拖拽、按键、滚动、截图与多标签）；前端右侧提供实时 Web 交互面板，支持快照串流渲染与无缝人机协同交互接管。
  • 📊 原生企业级 ChatBI 与自愈分析 (ChatBI & Self-Healing)：数据源与元数据管理、元数据一致性巡检与 Schema 漂移治理、案例集 Few-Shot、SQL 自愈与 sql_plan 结构化计划；我的数据门户（/dataset_portal）个性化导航；支持直连物理 SQL 与黄金报表暂存订阅。
  • 🧠 长期记忆与跨会话回顾 (Memory & LTM)：LTM 偏好注入 + 内置 memory_search 按需检索会话/每日摘要；记忆管理中心提供向量检索运维与数据治理；全链路 Redis 会话记忆与压缩日志 TTL 全面升级为 30 天。
  • 📊 上下文分项拆解观测与溢出智能压缩 (Context Observability & Compaction)：精准实时拆解 System Prompt、Tools Schema、Memory/History 与 Current Turn 四大项 Token 占比；支持自动水位线告警与两阶段结构化压缩（_structured_tool_block 精准提炼、保留多模态附件标记）。
  • 🧩 代码画布与工作区执行 (Code Canvas & Workspace)：支持 Python / Shell 代码的流式运行、停止、输出回传与私有工作区文件预览；支持 publish_generated_file 智能工件发布与有效期管理。
  • 📚 可视化知识库管理中心 (RAG & Knowledge Hub)：非结构化文档树形管理、召回测试、语义合并；Knowledge 执行器在 ReAct 前自动检索并注入引用。
  • 🔌 双向企业级 MCP 生态 (Platform & Client MCP)：出站调用外部 MCP 工具时自动透传用户身份上下文保障多租户与权限隔离；同时原生对外提供 NanZi Platform MCP 服务（OAuth2 鉴权与服务台），支持 Cursor、Claude Desktop 等外部客户端免改造调用 NanZi 智能体、会话与元数据。
  • 🔌 灵活的嵌入式 (Embed) 集成：通过嵌入式 Chat SDK 快速集成至企业业务系统，对接现有鉴权体系，实现租户隔离、RBAC 权限与水印安全合规。
  • ⏰ 自动化任务中心与多通道推送 (Task Scheduler & Notifications)：APScheduler + Redis 执行期锁，支持通过环境变量指定唯一调度节点，模拟智能体身份自主执行周期（Cron）、定时与间隔任务；支持 多通道智能触达（企业微信、钉钉、飞书、邮件、自定义 Webhook 及站内信通知中心）；内置自动剥离思考过程（纯净业务摘要推送）、超长截断保护与黄金报表异常阈值告警。
  • 🛠️ 全链路 Debug 与 Trace：决策链、工具调用、SQL 计划卡片可视化；结构化查数结果 CSV/Excel 导出。
  • ⚙️ 标准化 API 开放：标准化 V1 API 接口，支持外部系统通过 API 直接调用智能体编排与执行能力。
  • 🎯 提示词工厂 (Prompt Factory)：系统提示词版本管理与草稿（architech/prompts/），生产行为可控可审计。

🏛️ 系统架构 (Architecture)

Architecture

End-to-End Flow

┌──────────────────────────────────────────────────────────┐
│                     NanZi 智能体平台                     │
└───────────────┬────────────────────────────┬─────────────┘
                │                            │
   [ 嵌入式聊天 SDK ]                [ 管理控制后台 ]
   (Embed Chat SDK)                 (Admin Console)
                │                            │
                └─────────────┬──────────────┘
                              │ SSE/HTTP
┌─────────────────────────────▼────────────────────────────┐
│                  核心网关 (Portal Gateway)               │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │ 统一鉴权 │  │ Main 委派 │  │ 任务调度 │  │ 审计回溯 │  │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │
└─────────────────────────────┬──────────────┬─────────────┘
                              │              │ (状态与队列)
                              │        ┌─────▼─────┐
                              │        │   Redis   │
                              │        └───────────┘
┌─────────────────────────────▼────────────────────────────┐
│                智能体专家集群 (Expert Pool)               │
│   ┌──────────────┐      ┌──────────────┐     ┌─────────┐  │
│   │  ChatBI 专家 │      │ RAG 知识专家  │     │ 插件助手│  │
│   └──────┬───────┘      └──────┬───────┘     └───┬─────┘  │
└──────────┼─────────────────────┼─────────────────┼────────┘
           │ (ReAct 循环)        │ (托管路由)      │ (工具链调用)
┌──────────▼─────────────────────▼─────────────────▼────────┐
│                智能体运行引擎 (Execution Engines)         │
│  ┌──────────────────┐  ┌──────────────┐  ┌─────────────┐  │
│  │ AgentScope ReAct │  │ RAGFlow Agent│  │  OpenClaw🦞 │  │
│  │ (Loop & 自愈SQL) │  │  (托管智能体) │  │ (AUTH上下文) │  │
│  └────────┬─────────┘  └──────┬───────┘  └──────┬──────┘  │
└───────────┼───────────────────┼─────────────────┼─────────┘
            │                   │                 │
┌───────────▼───────┐ ┌─────────▼─────┐ ┌─────────▼────────┐
│ 企业多源数据仓/DB │ │ RAGFlow 知识库 │ │   MCP Server     │
│ (Oracle/CK/MySQL) │ │ (非结构化数据) │ │ (外部系统/API)    │
└───────────────────┘ └───────────────┘ └──────────────────┘

🖼️ 界面预览 (Interface Snapshots)

📊 仪表盘概览 (Overview Dashboard)💬 智能助手对话 (AI Chat)
仪表盘概览智能助手
🧠 长期记忆与无感回忆 (Memory & LTM)🔍 记忆管理控制台 (Memory Manage)
记忆与偏好记忆管理控制台
🛠️ 决策链路调试 (Trace Timeline)📚 知识库工作台 (Knowledge Hub)
调试链路知识库
🤖 智能体编排 (Agent Studio)📝 提示词游乐场 (Prompt Playground)
智能体提示词
🔌 直连物理数据源 (Data Sources)📊 元数据智能构建 (Metadata)
数据源元数据
⚡ 智能体动态技能 (Agent Skills)⚙️ 系统管理设置 (System Settings)
技能系统配置

🌟 核心能力 (Core Capabilities)

NanZi 核心能力矩阵

1. 🧠 多引擎与混合编排 (Multi-Engine & Hybrid Orchestration)

  • 智能委派：未指定智能体时直接进入 Main，由 Main 根据任务判断直接回答，或通过 sub_agent_call / sub_agent_batch_call 按需委派已授权专家；不再增加外层语义路由 LLM。
  • 专家直选：Embed 专家模式、agent_id 或 @ 提及保持直达指定智能体；指定专家后仍可由该专家继续委派其他子代理。
  • AgentScope ReAct：Assistant / ChatBI / Knowledge 基于 AgentScope Agent + Toolkit，闭环调度本地工具，支持权限挂起与恢复。
  • 主助手增强：工具预检（按绑定工具相关度促发调用）、Skill 自动扫描、反业务数据幻觉 Guard（可一键切换 ChatBI）。
  • 思考模型兼容层：支持 DeepSeek-R1、Kimi 等思考模型展开与 6 级 reasoning_effort 调优，自动挂载 tool_choice_for_model 确保工具稳定触发。
  • RAGFlow 托管 Agent：对接 RAGFlow 在线托管智能体，复用其检索与流式对话能力。
  • OpenClaw🦞 安全网关：通过 AUTH_CONTEXT 透传用户身份、频道及可访问数据集，保障租户隔离。

2. 🛡️ 多策略安全沙箱与隔离执行 (Multi-Policy Sandbox & Isolation)

  • 五大沙箱策略：原生支持 Local（本机安全隔离）、Docker（私有容器隔离）、K8s（Kubernetes 原生 Pod 沙箱隔离）、E2B（云端安全沙箱）、SSH（远程服务器安全通道）。
  • SSH 远程沙箱前提条件：ssh 策略由平台主机自身的 ssh CLI 连接远端主机，平台主机（或平台容器）需具备 openssh-client；密码认证额外需要 sshpass（私钥认证无需），且因固定启用 StrictHostKeyChecking=yes，远端主机密钥必须预先录入 known_hosts。完整依赖清单与报错对照见 FAQ 7.3.7 SSH 沙箱运行前提条件与连接排查。
  • 云原生 K8s Pod 沙箱：Kubernetes 集群生产部署免挂载宿主机 Docker Socket（/var/run/docker.sock），通过 K8s API 动态拉起隔离 Pod，借助平台 PVC 的 subPath 挂载用户工作区，保障金融/政企级安全合规。
  • 工作区物理同径 / subPath 挂载：用户工作区直接挂载进容器/Pod，自动将逻辑工作区路径转义映射至宿主机/PVC 物理文件，支持右侧代码画布直接打开、预览并保存回物理磁盘。
  • 沙箱生命周期自动化：支持后台 30 分钟空闲自动销毁（Idle Reaper）、服务重启优雅停机清理，定制生命周期适配器保护共享存储绝不误删。
  • 输入框浮标控制台：右上角上下文浮标无缝聚合沙箱状态（🟢已运行/🟡启动中/🔴失败/⚪未启动）、当前分配容器/Pod ID、实时秒级运行时长以及手动启动/重启/停止控制。

3. 🌐 服务端持久化浏览器会话与实时接管 (Persistent Browser & Live Takeover)

  • 完整自动化套件：支持打开网页、元素点击、表单输入、拟人轨迹滑块拖拽、智能等待、按键、全页滚动、文件上传、截图与多标签页管理。
  • 右侧 Web 交互面板：前端支持持久化浏览器面板，快照串流实时呈现；支持用户随时点击接管人工输入或验证码交互，人机协同闭环。

4. 📊 上下文智能预算与溢出压缩 (Context Management & Observability)

  • 四维分项拆解与可视化：精确估算并呈现 System Prompt、Tools Schema、Memory/History 与 Current Turn 的 Token 占比条形图。
  • 智能溢出压缩：触发物理窗口阈值时自动触发两阶段结构化压缩，提炼工具调用产物（_structured_tool_block）并保留重要多模态图片标识。
  • 30 天长期记忆缓存：全链路 Redis 记忆会话、压缩日志与生成工件下载链接全面升级为 30 天长效保存。

5. 📊 智能数仓分析 (ChatBI & Self-Healing)

  • Text-to-SQL 闭环：元数据注入 + Schema 门禁 + 多层 SQL 护栏，自然语言直查业务库。
  • 我的数据门户：系统指令 /dataset_portal（兼容旧 /dataset_menu），按权限生成数据集导航与 quick 追问。
  • 案例集与 Few-Shot：经验库审核入库，相似案例动态注入提示词头部提升专有 SQL 准确率；案例向量同步目标按检索模式自动区分（RAGFlow 模式同步 RAGFlow+本地 Redis，本地模式仅同步本地 Redis 向量）。
  • 自愈与计划推演：SQL 报错自动修复轮次；可选 enable_sql_plan 要求高风险查询先输出结构化 <sql_plan>（前端卡片展示）。
  • 连续分析工作流：非查数请求可本地回答或无感委派；结果栈支持引用、条件继承下钻、混合任务串行执行，并区分结果分析、呈现、动作和新查数。
  • 元数据业务导航：字段与口径回答基于授权 Schema 生成指标、维度和可执行问题；澄清候选不使用模型臆造字段。
  • 分析交付闭环：查询结果可一键生成证据化 Markdown/Word 业务简报，或转为黄金报表订阅，配置阈值、变化率、连续命中和无数据告警。
  • 数据源管理：可视化管理 Oracle / ClickHouse / MySQL 等连接，支持 DDL 抓取与连接别名唯一校验；支持黄金报表暂存与直连物理 SQL 执行。
  • 元数据巡检与 Schema 漂移治理：直连物理数仓定期体检（零 Token 消耗）与运行时报错自动反哺；精准识别表/字段缺失与类型不匹配，支持一键人机协同校准、变更日志 Diff 审计与多通道告警推送。

6. 🔌 双向开放插件生态 (MCP Integration)

  • 出站连接与用户上下文透传：智能体调用外部 MCP 工具时，在协议层自动透传当前登录用户身份上下文（用户、角色、租户与数据范围），确保下游外部系统实施精准的多租户隔离与操作审计。
  • NanZi Platform MCP 对外服务：平台原生作为 MCP 资源服务端，支持标准 OAuth2 鉴权与「MCP 服务台」管理；使 Cursor、Claude Desktop 等外部客户端可直接检索与调用 NanZi 纳管的智能体、会话与数仓元数据。
  • 无限生态连接：无需修改平台核心代码，即可双向对接生产力系统与多 Agent 协作生态。

7. 📚 深度知识增强与集成 (RAG & Knowledge Hub)

  • 一站式知识库管理：树形文档管理、切片预览、召回测试、语义合并与生命周期审计。
  • Knowledge 执行器：对话中自动 search_knowledge_base 预检索，ReAct 阶段注入引用卡片，空召回/无引用回答可拦截。
  • RAGFlow 托管路径：亦可一键对接 RAGFlow 托管知识智能体，复用外部检索与流式底座。

8. 🛠️ 企业级配套与安全审计 (Enterprise Toolkit & RBAC)

  • 自动化任务中心与多通道推送：APScheduler + Redis 执行期锁，支持通过环境变量指定唯一调度节点，模拟智能体身份执行周期（Cron）与定时任务；支持企微、钉钉、飞书、邮件、Webhook 与站内信 (Inbox) 多通道智能触达，自带思考内容清洗（正文纯净推送）与超长截断保护。
  • 黄金报表智能告警：支持 ChatBI 报表定时巡检，配置阈值告警、变化率偏离、连续命中与无数据告警并自动推送通知。
  • 多提供商模型管理：内置 OpenAI, Azure, DeepSeek, Kimi, 智谱 AI, 硅基流动, 阿里云百炼, 火山引擎 (Ark/豆包), Ollama 等模型预设与 Endpoint 智能版本号规范化。
  • 平台时区配置：系统调度和未单独指定时区的订阅按 platform_timezone 解释时间，默认 Asia/Shanghai。
  • 精细化 RBAC：用户、角色、菜单与元素级权限，读写操作隔离。
  • SSO 与脱敏：SSO 登录可后台开关；审计日志自动脱敏密码、API Key 等敏感字段。
  • 安全审计水印：Embed 窗口背景水印（用户名+时间戳或自定义文案），防截屏外泄。
  • 链路可视化与导出：Trace 时间线调试；查数结果 CSV/Excel 导出（utf-8-sig）。

🔄 智能体工作流 (Execution Flow)

系统底层基于 6 阶段异步流水线 (PipelineRunner) 驱动，遵循 「确定入口 → 委派/分发 → 执行 → 交付」 链路：

  1. 入口解析 (Route)：
    • 显式指定：传入 agent_id / agent_name / version_id，或正文含 @ 提及、进入专家模式时，直达目标专家；
    • 快捷下钻：点击查数结果操作胶囊时，自动直通 ChatBI 数据查询专家；
    • 默认兜底：未指定时直接加载默认主助手 Main（免去外层重度语义路由开销）。
  2. 智能委派 (Delegation)：
    • 仅限已启用的平台系统智能体 (is_system=True) 进入委派候选池（普通自定义智能体不参与自动委派）；
    • 主助手结合任务诉求，可直接作答，或调用 sub_agent_call（串行）/ sub_agent_batch_call（并行）委派子专家；内置防自委派、递归深度与权限安全门禁。
  3. 执行分发 (Dispatcher)：
    • 按引擎与能力精准路由至 Knowledge / ChatBI (DataQuery) / Assistant / RAGFlow / OpenClaw 执行器；
    • ChatBI 内部自主完成新查数、结果复用、上下文动作、元数据与澄清分诊。
  4. 动态执行 (ReAct)：
    • 基于 AgentScope「思考-行动-观察」循环，原生集成 SQL 语法护栏、HITL 人机协同审批确认、问答卡中断及浏览器会话面板联动。
  5. 结果交付与合成 (Synthesis)：
    • 动态委派由父级助手统一汇总输出；并行协同场景由独立的 Synthesizer 模型完成多专家答案聚合；全链路 SSE 流式下发正文、思考日志与引用溯源。

详见 architech/design/chat/CHAT_FLOW.md · 智能委派与专家直选设计

📚 文档与架构 (Documentation)

文档说明
微信实战连载架构分层、安装部署、智能体配置、ChatBI、工具箱、MCP
HOW_TO_INSTALL.md安装部署与 FAQ
architech/README.md架构文档索引
CHAT_FLOW.md聊天端到端流程
PROMPT_LAYERS.md提示词分层与注入
AGENT_ROUTING_DESIGN.md智能委派与专家直选设计
mcp-business-integration-authentication-design.mdMCP 业务集成认证总体架构、安全策略与调用流程
mcp-platform-inbound-service-design.mdNanZi 平台级 MCP 对外服务、OAuth2 授权、管理页与元数据方法方案
api_integration_guide.mdEmbed / V1 API 集成
mcp_user_context_integration_guide.md自有 MCP UserContext 接入、JWKS 验签及 Python / Java 示例
mcp_echo_test_server.md平台级 MCP Echo 测试服务创建、智能体挂载与认证诊断
code_canvas_and_workspace_guide.md代码画布、工作区文件与执行 API
sandbox/docker/README.mdDocker 安全沙箱预构建与运维指南（含排障工具链、--dry-run 与 --list）
sandbox/k8s/README.mdK8s 沙箱预置镜像构建与运维指南（冷启动加速、k8s_deploy 运维与监控）
FAQ 7.3.7 SSH 沙箱运行前提条件与连接排查SSH 沙箱（ssh 策略）sshpass / openssh-client / known_hosts 前置依赖与报错对照
ai_agent_gating_contract.mdAgent 门控契约
tests/CHECKLIST.md自动化测试验收清单

📂 项目结构 (Structure)

.
├── app/                  # 后端核心代码 (FastAPI 异步架构)
│   ├── api/              # API 路由层 (Portal 运营端与 V1 客户端 REST/SSE 接口)
│   ├── core/             # 系统核心基础设施 (全局配置、数据库引擎、安全加密、生命周期)
│   ├── models/           # SQLAlchemy 2.x 数据库 ORM 实体模型
│   ├── schemas/          # Pydantic 契约与 DTO 数据校验模型
│   ├── services/         # 核心业务服务层 (鉴权、模型管理、ChatBI、RAG、MCP 调度)
│   │   └── ai/           # 🤖 AI 编排中心 (AgentScope 运行器、OpenClaw 执行器、意图分发器)
│   └── utils/            # 通用工具库 (加解密、向量算子、数据转换与辅助工具)
├── frontend/             # 前端工程 (Vue 3 + Vite + TypeScript + Tailwind CSS)
│   └── src/
│       ├── api/          # 前端接口请求层与后端契约映射
│       ├── views/        # 业务页面 (控制台、智能体编排、ChatBI、知识库、技能中心等)
│       ├── components/   # 通用 UI 组件与聊天流式卡片
│       ├── composables/  # Vue 组合式状态逻辑 (SSE 流式会话、权限管理)
│       └── router/       # 动态路由与菜单权限控制
├── .agent/               # Agent 自动化开发技能与工作流体系 (opsx、dev-skills 等)
├── architech/            # 顶层架构设计、契约规范与系统提示词 (Prompts) 管理中心
├── data/                 # 平台持久化运行数据 (工作区、沙箱运行时、技能资产、文件上传)
├── db-prod/              # MySQL 历史版本迁移与 SQL 升级脚本 (V0-VNN)
├── db-prod-pg/           # PostgreSQL 基线与幂等版本迁移体系 (V0-VNN)
├── docker/               # 容器化镜像构建方案与 docker-compose 一键启动编排
├── docs/                 # 项目架构文档、发布记录 (Release Notes) 与品牌设计规范
├── html/                 # 平台单页产品落地宣传页 (Landing Page)
├── k8s_deploy/           # 云原生生产级 Kubernetes 编排清单与沙箱隔离集群运维套件
├── sandbox/              # 📦 运行时代码沙箱运维目录 (docker/k8s)
├── scripts/              # 运维/开发辅助脚本 (一键开发启动、数据同步、重部署工具)
├── tests/                # 自动化测试套件 (Pytest) 与测试验收清单 (CHECKLIST.md)
├── dev.sh                # 🛠️ 本地一键开发启动、热编译与前后端进程启停运维脚本
├── env.example           # ⚙️ 全局环境变量与系统核心敏感配置示例模板
├── requirements.txt      # 📦 后端 Python 核心运行时依赖清单 (Python 3.11)
└── pytest.ini            # 🧪 自动化测试套件运行与断言配置

📌 根目录关键脚本与配置文件说明

文件类型核心职责说明
dev.shShell 脚本本地一键开发运维总控：支持前后端并行启动、热编译重载、前台/后台运行模式切换、环境探测与进程优雅启停。
sandbox/docker/build-docker-sandbox-image.shShell 脚本Docker 代码安全沙箱预构建：提前拉取并构建带安全隔离的 Python 3.11 沙箱镜像，大幅加速 Agent 动态执行代码时的启动速度。
env.example配置模板全局环境变量基准模板：包含 MySQL/PostgreSQL、Redis Stack、JWT/加密私钥、模型 API 端点等核心运行参数。
requirements.txt依赖配置后端运行时依赖包清单：基于 Python 3.11 的核心第三方库依赖定义（FastAPI、AgentScope、SQLAlchemy、Redis 等）。
pytest.ini测试配置自动化测试套件配置：定义 Pytest 用例过滤规则、异步标记、控制台日志输出与测试运行行为。

🚀 快速开始

🐳 Docker 部署 (推荐)

1. 配置环境

cd docker
cp ../env.example .env   # 配置数据库、Redis、ENCRYPTION_KEY 等

平台主库默认使用 MySQL；如需使用 PostgreSQL，编辑 docker/.env：

DATABASE_TYPE=postgresql
POSTGRES_HOST=host.docker.internal
POSTGRES_PORT=5432
POSTGRES_DB=nanzi_ai_agent_platform
POSTGRES_USER=postgres
POSTGRES_PASSWORD=<password>

容器中的主库 Host 不能填写 localhost 或 127.0.0.1，应使用宿主机地址、 host.docker.internal 或 Docker 网络中的服务名。详细初始化步骤见 HOW_TO_INSTALL.md 和 db-prod-pg/README.md。

主库初始化

MySQL 使用 db-prod/apply-sql.sh；PostgreSQL 使用独立的幂等迁移入口：

# 返回项目根目录执行
cd ..
./db-prod-pg/apply-sql.sh

该脚本会按 db-prod-pg/ 中当前存在的 V0～V14 版本顺序执行 PostgreSQL 迁移，并在首次初始化后询问是否创建管理员。以后新增迁移时，以该目录实际文件为准，不要把 PostgreSQL 迁移和 db-prod/ 的 MySQL 迁移混用。 PostgreSQL 不使用 MySQL 的 INIT-USER-ADMIN.sql 固定凭证；如需手动维护管理员，可执行：

./db-prod-pg/create-admin-user.sh
./db-prod-pg/create-admin-key.sh
./db-prod-pg/reset-admin-password.sh

2. 构建镜像并导出 tar

脚本目标环境
./build_linux_x86.shx86_64 Linux 服务器（最常见）
./build_linux_arm.shARM64 Linux（鲲鹏 / Ampere 等）
./build_native.sh本机原生架构，仅用于本地试跑
# 若上一步返回了项目根目录，先进入 docker 目录
cd docker
# 生产环境（x86 服务器）— Mac 上打 x86 包也用此脚本
./build_linux_x86.sh

产物输出至 docker/release/，例如 nanzi-ai-agent_linux-amd64_20250527.tar。离线部署可在目标机执行 docker load -i docker/release/xxx.tar。

Mac（Apple Silicon）部署到 x86 服务器时，务必使用 build_linux_x86.sh，不要用 build_native.sh。首次跨平台构建拉取基础镜像时可能较长时间无新日志，属正常现象。

若提示 docker buildx 不可用（Homebrew docker + Colima 常见，cli-plugins 仍指向已卸载的 Docker Desktop）：

cd docker
./install-buildx.sh
./build_linux_x86.sh

详见 docker/README.md · docker/README_EN.md

3. 启动服务

./start-nanzi-ai-agent.sh

🛠️ 开发与部署工具

1. 本地一键开发联调 (强烈推荐)

对于日常本地开发，推荐使用项目根目录下的一键集成脚本：

./dev.sh

该脚本首次运行会自动检测并安装 uv，准备 Python 3.11、创建 .venv 并安装后端依赖；后续仅在 requirements.txt 变化时更新依赖。随后脚本会停止旧的 API_SERVICE_PORT 进程（默认端口 8001）、编译前端（跳过类型检查以提速）并以前台 reload 模式拉起后端 FastAPI 服务，您可以在当前终端中实时查看联调日志与输出。

如需后台运行，可使用以下生命周期命令：

# 后台启动，PID 保存到 .dev-server.pid
./dev.sh -d

# 查看 PID、端口监听和 /health 健康状态
./dev.sh status

# 优雅停止后台服务，超时后自动强制停止
./dev.sh stop

status 和 stop 不会重新安装依赖或编译前端；端口监听探测优先使用 lsof，缺失时自动回退到 ss/fuser。脚本可识别以绝对/相对 .venv 路径或 python3 -m uvicorn 等形态启动的本项目 Uvicorn；若仍无法确认归属（或确实被其他进程占用），会列出监听 PID 及命令行并拒绝误杀，便于人工核对。

启动顶部还会打印 uv、Python 目标版本、虚拟环境、PyPI 镜像、DATABASE_TYPE、数据库地址和 Redis 地址等配置摘要；数据库和 Redis 密码不会单独打印。这些信息仅用于确认当前配置，不代表数据库或 Redis 连通性测试已经通过。

运行前的环境准备（.env）：脚本首次运行前必须先编辑 .env 配置文件。项目根目录提供了模板 env.example，请先基于它创建 .env 并填写为你的实际环境：

cp env.example .env

然后按需修改 .env 中的关键项：

  • 数据库：DATABASE_TYPE（mysql 默认 / postgresql），以及对应的 MYSQL_* 或 POSTGRES_* 主机、端口、库名、账号与密码；
  • Redis：REDIS_HOST、REDIS_PORT、REDIS_DB、REDIS_PASSWORD（无密码时留空）；
  • 任务调度：TASK_SCHEDULER_ENABLED（默认 true）；多节点部署时只在一个节点开启，其他 API 节点设为 false；
  • 加密密钥：ENCRYPTION_KEY（API Key 的对称加密密钥，可保留模板默认值，生产环境务必更换为独立的 Fernet Key）；
  • 可选集成：SSO、RAGFlow、Jira 等信息按需填写。

一键脚本仍需要本机具备 Node.js/npm，并且需要提前准备 .env、数据库和 Redis；uv、Python 与 Python 依赖的首次下载需要网络。若 PyPI 镜像需要调整，可通过 PYPI_INDEX_URL 覆盖默认的清华镜像地址。

🤝 贡献指南

  1. 分支规范: 基于 main 分支开发，功能分支命名格式 feature/your-feature-name。
  2. 提交信息: 必须使用 中文 编写 Commit Message，清晰描述变更内容。
  3. 测试验收: 新增功能时，请更新 tests/CHECKLIST.md。

💬 联系与交流

如果您在使用过程中有任何疑问、功能建议，或者想要获取更多技术资讯，欢迎扫码关注我们的微信公众号，或加入微信交流群；亦可阅读 NanZi 开源智能体平台实战连载：

微信公众号
微信公众号 		微信交流群
微信交流群（7天内有效）

扫码进群获取平台免费体验账号和地址。

💖 支持与赞赏

NanZi AI 智能体平台是一个完全开源且持续迭代演进的项目。如果本项目在学习、工作或业务落地中对您有所帮助，欢迎请作者喝杯咖啡 ☕！

您的每一份支持，都是激励项目持续打磨架构、扩展核心功能与维护高质量文档的巨大动力。衷心感谢所有支持开源的小伙伴！

微信赞赏支持
微信赞赏支持（作者 NanZi）

📄 许可证

本项目采用 MIT 开源许可证，允许自由使用、复制、修改、合并、发布、分发、再许可及销售本软件副本。

Copyright © 2025-2026 Randy Chen cexlong@gmail.com. All Rights Reserved.

Collected info

  • ★ 178 stars
  • ⎇ 50 forks
  • Language: Python
  • Source updated: 9/23/2026