综合白泽 Baize 部署笔记：Docker Compose 起中心服务，宿主机装 Agent 纳管服务器

2026-09-17 20:01:33

白泽 Baize 部署笔记：Docker Compose 起中心服务，宿主机装 Agent 纳管服务器

项目信息

仓库（公开部署入口）：https://github.com/ysfl/baize
官网：https://baize.run/
在线预览：https://baize.run/
发布与镜像：Release、中心服务镜像、控制台镜像
交流：Discord https://discord.gg/UMR7mnZFqh 、Telegram https://t.me/+y3n_66PfRSw0ZDRl 、邮件 support@baize.run

白泽（Baize）是自部署的服务器管控平台。在一台服务器上启动白泽，再给每台要纳管的服务器装上轻量 Agent，就能在同一个控制台里做资产纳管、实时监控、安全防护、远程运维和操作审计。数据留在自己的服务器上，不依赖外部托管。

仓库本身提供的是 Docker Compose 编排、安装与升级脚本、备份恢复工具和版本清单。中心服务、节点 Agent 与控制台以容器镜像和公开发布包形式分发，需要从镜像仓库或 GitHub Releases 获取。

核心能力

资产纳管：接入服务器后统一查看在线状态、配置与负载，按需分组管理。
全栈监控：CPU、内存、磁盘、网络、进程、服务、Nginx、Docker、SSL 证书，多维度指标采集与可视化。
安全防护：边缘 WAF、SSH 暴力破解检测、攻击 IP 联防，证书与防火墙状态统一观测。
远程运维：网页终端、批量命令执行、文件分发、服务管理，关键操作可审计记录。
任务编排：分布式定时任务管理，多节点协同执行，结果统一收集。
告警审计：规则引擎、告警升级、静默策略与多渠道推送；关键操作留痕，事后可追溯。

适用场景

自建或私有化部署的团队，希望数据不出自己的服务器；手上几台到几十台服务器，想统一纳管；需要关键操作留痕以应对合规要求；正在用一堆分散脚本做运维、想收敛成一个入口。

架构：边缘智能 · 中心调度

中心服务负责汇聚与调度，每台被纳管服务器上的轻量 Agent 负责采集、执行与边缘防护。控制台、移动端和开放集成共用同一套管控入口。

AI 客户端接入

git clone https://github.com/ysfl/baize.git
cd baize
bash scripts/install-ai-access.sh --lang zh

scripts/install-ai-access.sh 只安装本机 AI 接入组件，不安装白泽中心服务、控制台或 Agent。安装白泽产品仍然使用 scripts/install.sh。

安装器会自动识别本机已安装的客户端并完成注册。Codex CLI、Claude Code、ZCode 和 DeepSeek Harness（DSH）还会同时安装 Skill：

Codex CLI（codex mcp 注册）、Claude Code（claude mcp 注册）
ZCode（~/.zcode/cli/config.json）
Gemini CLI（~/.gemini/settings.json）
Qwen Code（~/.qwen/settings.json）
Cursor（~/.cursor/mcp.json）
Windsurf（~/.codeium/windsurf/mcp_config.json）
VS Code（GitHub Copilot）（用户配置 mcp.json）
Cline（cline_mcp_settings.json）
Trae（~/.trae/mcp.json）
DeepSeek Harness（DSH）（$DSH_HOME/cordis.patch.yml）

注册只写入 MCP 启动命令，不写入白泽地址或登录凭据；配置文件中已有的其它服务器会保留。也可以用 --client 指定单个客户端（如 --client zcode），或用 --client manual 跳过自动注册并打印手动配置。

安装后，在本机交互式终端运行安装器提示的 baize-mcp login 命令，再重新打开 AI 客户端。地址和登录会话保存在当前系统用户的本地配置与凭据存储中。AI 应优先使用已配置的受控白泽 API；没有 API 工具时使用 MCP。当前正式版支持节点查询与运行概览、节点与平台观察、只读运行态诊断、告警、命令模板与命令计划、远程任务闭环（直接执行、派发、进度、按需输出、取消）和工作流状态工具。API 和 MCP 创建的任务都会留下远程任务和审计记录。

Windows 使用 scripts/install-ai-access.ps1。

更新 AI 接入组件：已有 MCP 或 Skill 时不需要重新登录，也不要使用白泽产品的 scripts/upgrade.sh。在之前克隆的 baize 目录中运行：

bash scripts/upgrade-ai-access.sh --lang zh

5 分钟快速开始

准备一台 Linux 服务器（2 vCPU / 4 GB 内存 / 20 GB 磁盘起步），装好 Docker，然后：

git clone https://github.com/ysfl/baize.git
cd baize
bash scripts/install.sh

安装脚本会引导完成配置。中文安装可选择 GitHub 或 ACR 下载来源，中国大陆推荐 ACR。脚本先确认端口，再根据端口提示访问地址。随后自动生成强随机的数据库密码、Redis 密码、JWT 密钥、管理员初始密码、凭据主密钥和高敏操作安全码，并拉起默认的完整部署。首次运行会尝试准备离线 GeoIP 数据库；网络受限时会提示原因并继续启动核心服务。安装中断或失败后可直接重跑，脚本会保留现场并输出检查命令。

手动配置方面，基础模板见 .env.example（英文 .env.en.example）；性能、队列、调度器、外部日志和 AI 模型等低频调优项见 .env.advanced.example。生产环境建议优先用安装脚本生成 .env，避免复用示例密钥。

默认访问地址：

控制台 http://<你的服务器IP或域名>:8088
服务地址 http://<你的服务器IP或域名>:22501/api/v1

管理员初始账号 admin，初始密码写在 .env 的 ADMIN_PASSWORD 中。主机画像刷新、命令历史明文查看等高敏操作使用独立安全码，初始值在 .env 的 BAIZE_HOST_PROFILE_SECURITY_CODE 中。首次登录后请立即修改密码，并妥善保管 .env，不要提交到 Git。

装好之后做什么

登录并改密。
接入第一台节点——在控制台创建注册令牌后，到目标服务器宿主机上执行：

bash scripts/install-agent.sh --server http://<你的服务器IP或域名>:22501 --token <注册令牌>

--server 必须填写你自己的白泽访问地址，安装器不会内置任何默认控制端。Agent 建议直接装在被纳管服务器的宿主机上，不建议放进容器，以便读取进程、磁盘、Docker、防火墙等宿主机状态。

逛一圈——监控看实时指标、安全看 WAF 与登录风控、审计看操作留痕。
配域名访问策略（生产建议）——减少 IP 直连与未知 Host 进入控制台。

版本与升级

控制台右上角会在有新版本时提示。升级前先备份：升级会自动备份，但数据结构变更不会自动回退，出问题需从备份显式恢复。保留部署配置（.env 中的 BAIZE_STACK_MODE 等）。通过反向代理访问的，从 0.2.2 起默认不信任任何代理来源，需要在 .env 中用 SERVER_TRUSTED_PROXIES 声明代理网段。

当前正式版本发布在 GitHub Releases。安装时选择 GitHub 会使用 GHCR 和 Docker Hub，选择 ACR 会使用阿里云镜像、国内镜像加速地址和 Gitee 版本清单。

支持单组件更新的镜像版本发布后，可在“系统版本”页分别更新 Server 或 Web。该操作由宿主机上的本机执行器完成，只替换所选组件并校验镜像摘要和健康状态；Server 容器不会获得 Docker Socket。最新版本清单带有可信镜像摘要时（0.2.2 起），单组件更新即可使用；摘要缺失的版本会保持按钮不可用。

bash scripts/version.sh --check-remote   # 对比远端最新版本
bash scripts/upgrade.sh                 # 执行升级（自动备份 + 失败向导）

常见问题

装完控制台打不开？ 先跑 bash scripts/check-install.sh。确认访问的是控制台端口（默认 8088）而非服务端口（22501）；server-only 模式不会启动控制台容器。
Agent 连不上中心服务？ 确认 --server 填的是被纳管服务器能访问到的白泽地址（带 http(s)://）、注册令牌未过期，且 Agent 装在宿主机而非容器内。
升级失败怎么回滚？ 升级脚本失败会进入处理向导，可直接恢复升级前的数据库与配置或切回旧版本；也可以 bash scripts/restore-backup.sh --latest --yes --require-db 手动回滚。
数据库数据卷坏了怎么办？ 从最近备份重建：bash scripts/restore-backup.sh --latest --yes --require-db --reset-volumes --i-understand-data-loss（破坏性，仅在确认需要时使用）。
卸载 / 迁移？ 先执行 bash scripts/uninstall.sh --yes。默认会先备份，再停止并移除容器，同时保留 Docker 数据卷、.env 和历史备份。只有确认不再需要数据后，才使用 --purge-data 或 --purge-all。
忘记密码 / 安全码？ 初始管理员密码在 .env 的 ADMIN_PASSWORD、安全码在 BAIZE_HOST_PROFILE_SECURITY_CODE。如果已经修改且忘记了当前值，在安装目录执行重置脚本即可。

取舍与注意

白泽是闭源商业软件。本仓库只作为公开部署入口，允许按 LICENSE 中的版权与使用声明部署、运行和维护自己的白泽实例；中心服务、节点 Agent、控制台及其镜像 / 发布包受独立商业授权约束，能拿到什么版本取决于授权与镜像仓库。
Agent 装宿主机，不装容器。放进容器会读不到宿主机的进程、磁盘、Docker 和防火墙状态，采集与执行能力都会打折。
升级不会自动回退。升级脚本会自动备份，但数据结构变更无法自动撤销，出问题只能从备份显式恢复，所以升级前手动确认一份备份更稳妥。
从 0.2.2 起默认不信任任何代理来源。走反向代理访问控制台的，必须在 .env 里用 SERVER_TRUSTED_PROXIES 声明代理网段，否则访问来源判定会不符合预期。
install-ai-access.sh 与产品安装、升级是两条线，别混用 upgrade.sh 去更新 AI 接入组件。

社区与支持

官网 https://baize.run/ ；Discord https://discord.gg/UMR7mnZFqh ；Telegram https://t.me/+y3n_66PfRSw0ZDRl ；问题反馈走 GitHub Issues；邮件 support@baize.run

复制全文生成海报自托管运维平台服务器管理 Docker-Compose MCP AI接入

综合 白泽 Baize 部署笔记：Docker Compose 起中心服务，宿主机装 Agent 纳管服务器