Bisheng 保姆级部署教程：开源企业级 LLM 应用 DevOps 平台，Docker Compose 一键起

一、项目介绍

Bisheng（「毕昇」，以活字印刷术发明者命名）是 DataElement 公司开源的一款面向企业场景的 LLM 应用开发与运维（DevOps）平台。官方 README 对其定位是：「an open LLM application devops platform, focusing on enterprise scenarios. It has been used by a large number of industry leading organizations and Fortune 500 companies」。平台内置任务模式（Task Mode，通用 Agent）、企业知识库（Knowledge Space）、外部资讯频道（Channels）、可视化工作流（BISHENG Workflow）、企业级权限与审计、高精度文档解析（OCR / 印章 / 表格识别）等能力，默认通过 Docker Compose 一键拉起，并附带 ES、Milvus、Onlyoffice 等第三方组件。

项目在 GitHub（dataelement/bisheng）持续活跃维护（核验日期 2026-11-01），被 Trendshift 收录为增长最快的开源仓库之一（README 内置 badge 指向 trendshift.io/repositories/717）。

二、功能拆解

按官方 README「Features」一节，Bisheng 的核心能力如下：

功能	说明（官方原文要点）
🚀 Task Mode 任务模式	通用多步骤 Agent：拆分目标、并行子代理、Human-in-the-loop、内置 PPT/Excel/Word 三个技能包，产出报告带引用标记
📚 Knowledge Space 知识空间	团队知识库：多级文件夹、标签、Owner/Manager/Editor/Viewer 权限模板、AI 问答并展示来源
📡 Channels 资讯频道	把微信公众号、网站聚合成每日更新的主题频道，按标题/正文规则过滤
🧩 BISHENG Workflow	独立完整编排框架：Chatflow 与 Workflow 不拆分，支持循环、并行分支、批处理、人工节点
🏢 企业级能力	部门/用户管理、RBAC + ReBAC、审批流、审计日志、SSO/LDAP、内容安全、国产化支持（MySQL / 达梦 DM8）
🔍 高精度文档解析	5 年高质量数据训练的印刷体 / 手写体 / 生僻字 / 表格 / 印章识别模型，可免费私有化部署

三、官方/GitHub 链接

GitHub 仓库：https://github.com/dataelement/bisheng
官方部署文档（Self-hosting Wiki）：https://dataelem.feishu.cn/wiki/BSCcwKd4Yiot3IkOEC8cxGW7nPc
BISHENG Workflow 文档：https://dataelem.feishu.cn/wiki/R7HZwH5ZGiJUDrkHZXicA9pInif
公司官网：https://dataelem.com/
仓库自带 README_CN.md（简体中文）/ README_JPN.md（日文）

四、环境要求

官方 README「Quick start」开头明确列出的硬性前置条件（原文）：

CPU： >= 4 虚拟核（Virtual Cores）
RAM： >= 16 GB
Docker： 19.03.9 及以上版本
Docker Compose： 1.25.1 及以上版本

官方推荐硬件配置：18 虚拟核、48GB 内存。除 Bisheng 本身外，默认还会通过 Compose 一并安装 Elasticsearch（ES）、Milvus 向量库与 Onlyoffice 文档服务，这是 16GB 起步要求的主要原因。

操作系统： 官方 README 未限定具体发行版，只要能跑 Docker 19.03.9+ 即可（Linux 服务器为主）。
端口： 启动完成后浏览器访问 http://IP:3001（官方原文），即 Web 控制台默认暴露 3001 端口。

五、部署步骤

步骤 1：拉取 Bisheng 代码（官方原命令）

git clone https://github.com/dataelement/bisheng.git
# Enter the installation directory
cd bisheng/docker

逐段解释：git clone 从 GitHub 拉取仓库；cd bisheng/docker 进入 docker 子目录——官方所有 Compose 编排文件都放在这里。

预期输出参考： 输出 Cloning into 'bisheng'... 进度，最终回到命令行提示符。

无 git 环境的替代下载方式（官方原文）：

# If the system does not have the git command, you can download the BISHENG code as a zip file.
wget https://github.com/dataelement/bisheng/archive/refs/heads/main.zip
# Unzip and enter the installation directory
unzip main.zip && cd bisheng-main/docker

逐段解释：wget 下载 main 分支的 zip 包；unzip 解压后进入 bisheng-main/docker 目录（与 git clone 等价）。

步骤 2：启动 Bisheng（官方原命令）

docker compose -f docker-compose.yml -p bisheng up -d

逐段解释：docker compose 调用 Compose 插件（Compose V2 语法，等价于旧版 docker-compose）；-f docker-compose.yml 指定编排文件；-p bisheng 指定项目名为 bisheng（便于后续按项目名管理容器）；up -d 创建并以后台（detached）模式启动全部服务。

预期输出参考： Compose 拉取镜像并创建容器的日志，形如：

text [+] Running 25/25 ✔ Network bisheng_default Created ✔ Container bisheng-es-1 Started ✔ Container bisheng-milvus-1 Started ✔ Container bisheng-redis-1 Started ✔ Container bisheng-postgresql-1 Started ✔ Container bisheng-bisheng-langgraph-1 Started ✔ Container bisheng-bisheng-backend-1 Started ✔ Container bisheng-bisheng-frontend-1 Started ...

首次启动需拉取多个镜像（含 ES、Milvus、Onlyoffice），耗时取决于网速。

步骤 3：浏览器访问

启动完成后，按官方原文：「access http://IP:3001 in the browser. The login page will appear, proceed with user registration.」——将 IP 替换为服务器实际 IP 或域名，进入登录页并注册账号。

六、配置参数详解

官方 README 未在 Quick start 节展开具体环境变量与配置项；实际的服务编排与参数集中在 bisheng/docker/docker-compose.yml 与同目录的 .env 文件中。官方部署 Wiki（https://dataelem.feishu.cn/wiki/BSCcwKd4Yiot3IkOEC8cxGW7nPc）是配置权威来源。部署时请按以下方式定位关键配置：

编排文件： bisheng/docker/docker-compose.yml——定义 backend、frontend、langgraph、postgres、mysql、es、milvus、redis、minio、onlyoffice 等一组服务的镜像、端口、卷、依赖关系。
环境变量文件： bisheng/docker/.env（如存在）——常见配置项包括外部访问地址、数据库密码、JWT 密钥、对象存储（MinIO）AK/SK 等；修改后需 docker compose up -d 重建生效。
默认对外端口： 3001（Web 控制台，官方原文）。
持久化数据： Compose 默认通过命名卷或宿主目录挂载 postgres、mysql、es、milvus、minio 等有状态服务的数据目录，升级容器镜像不会丢数据（具体卷名见 docker-compose.yml）。

严格按官方约定：不要自行新增官方 compose 中不存在的服务或环境变量；如需改端口、改密码，应在 docker-compose.yml 或 .env 现有字段内修改，并参考官方 Wiki 的 Self-hosting 章节。

七、启动与运维

启动 / 停止： 官方启动命令为 docker compose -f docker-compose.yml -p bisheng up -d；停止并移除容器使用等价的 Compose 命令 docker compose -f docker-compose.yml -p bisheng down（属 Docker Compose 通用子命令，非官方单独列出）。
查看状态： docker compose -p bisheng ps 列出本项目全部容器状态；docker compose -p bisheng logs -f backend 跟踪后端日志。
开机自启： Compose 编排中的服务默认通过 Docker 的 restart 策略在 Docker 守护进程启动后自动恢复（具体策略见 docker-compose.yml 各服务的 restart: 字段）。
修改端口： 编辑 docker-compose.yml 中 frontend 服务的 ports 映射（如把 3001:3001 改成 8080:3001），执行 docker compose -f docker-compose.yml -p bisheng up -d 让变更生效。
数据持久化： postgres / mysql / es / milvus / minio 等服务的数据卷由 docker-compose.yml 声明；升级前请先备份这些卷（属 Docker 通用运维，非官方单独章节）。
卸载与清理： 见第十节。

八、实操验证

浏览器打开 http://服务器IP:3001，应看到 Bisheng 登录页（官方原文：「The login page will appear」）。
点击注册，第一个注册的账号将自动成为系统管理员（官方原文：「By default, the first registered user will become the system admin」）。
以管理员身份登录后，应能看到：
- 「任务模式 / Task」入口——可创建通用 Agent 任务；
- 「知识空间 / Knowledge」入口——可上传文档、新建知识库；
- 「工作流 / Workflow」可视化画布入口；
- 「Channels / 频道」订阅入口；
- 「系统设置 / 部门与用户」管理入口。
上传一份 PDF / Word 文档到知识空间，等待解析完成后在该文档上发起一次 AI 问答，答案下方应展示引用来源片段（官方 README 中 Knowledge Space 一节原文：「Answers show their sources; click a source to open the original text at the cited location」）。

登录与安全（重要）

官方默认账号密码：无出厂账号。 Bisheng 不提供默认管理员账号；首次访问必须自行注册，且第一个注册的用户自动成为系统管理员（官方原文）。
登录地址： http://服务器IP:3001。
首次登录后修改密码： 登录后进入个人中心 / 个人资料页修改密码（具体入口按界面引导，官方 README 未单独列出 URL）。
密码重置方法： 官方 README 未单独说明忘记密码的命令行重置方式；可在管理员后台「用户管理」中重置其他用户密码；彻底遗忘管理员密码时，可参考官方 Self-hosting Wiki 的故障排查章节（https://dataelem.feishu.cn/wiki/BSCcwKd4Yiot3IkOEC8cxGW7nPc）。
密码配置存放位置： 用户账号与密码哈希存储在 Compose 编排的 PostgreSQL / MySQL 数据库中（具体由 docker-compose.yml 决定）；初始化密钥、JWT Secret、数据库密码等通过同目录 .env 或 docker-compose.yml 的 environment 段注入。
安全提醒：
1. 部署完成后必须立即修改管理员初始密码，并在公网暴露前配置好域名与 HTTPS 反向代理；
2. 不要把 3001 端口直接暴露在无鉴权的公网；
3. 生产环境请按官方 Wiki 配置 SSO/LDAP、审计日志与内容安全审核；
4. 默认 .env 中的示例数据库密钥务必替换。

九、故障排查

案例 1：docker compose up -d 后 3001 端口无法访问 / 页面长时间白屏

常见报错形式（浏览器端）：This site can't be reached / 502 Bad Gateway。
报错原因：backend 或 frontend 容器尚未就绪（首次启动 ES、Milvus 初始化较慢，frontend 可能先于 backend 启动导致反代失败），或宿主机 3001 端口被防火墙拦截。
分步解决：① docker compose -p bisheng ps 查看所有容器状态是否为 Up；② docker compose -p bisheng logs -f backend 跟踪后端启动日志，等待数据库迁移与索引初始化完成；③ 检查服务器安全组 / 防火墙是否放行 3001；④ 若 backend 一直退出，按日志报错对照官方 Self-hosting Wiki 排查。

案例 2：docker compose up -d 报 port is already allocated

报错原文（常见形式）：

Error response from daemon: driver failed programming external connectivity on endpoint bisheng-xxx:
Bind for 0.0.0.0:3001 failed: port is already allocated

报错原因：宿主机 3001 端口已被其他进程（如旧版 Bisheng、Nginx、其他容器）占用。
分步解决：① ss -ltnp | grep 3001 找到占用进程；② 停止旧进程，或编辑 docker-compose.yml 把 frontend 的 ports 改成未被占用的端口（如 8080:3001）后重新 up -d。

案例 3：内存不足，容器被 OOM Kill（Exited (137)）

报错原文（docker compose ps 中常见）：

bisheng-es-1      ...      Exited (137) 5 minutes ago

报错原因：官方硬性要求 RAM >= 16 GB；ES 与 Milvus 同时启动会占用大量内存，低于配置时容器被内核 OOM Killer 终止（退出码 137 = 128 + 9 = SIGKILL）。
分步解决：① 用 free -h 确认可用内存；② 扩容到官方推荐的 18 核 48GB；③ 或临时在 docker-compose.yml 中调小 ES / Milvus 的 JVM 与内存限制（需参考官方 Wiki 的资源调优章节，避免自行乱改）。

案例 4：拉取镜像超时 / net/http: TLS handshake timeout

报错原文（常见形式）：

Error response from daemon: Get "https://registry-1.docker.io/v2/": net/http: TLS handshake timeout

报错原因：国内服务器直连 Docker Hub 不稳定。
分步解决：① 配置 Docker 镜像加速器（/etc/docker/daemon.json）；② 或在能访问 Docker Hub 的网络环境下预拉镜像后导出 docker save / docker load 到目标服务器；③ 具体镜像清单以 docker-compose.yml 中 image: 字段为准。

十、升级、回滚与卸载

升级（官方未在 README 单独给出升级命令，按官方推荐路径）：

git pull
cd docker
docker compose -f docker-compose.yml -p bisheng up -d

逐段解释：git pull 拉取上游最新代码与最新 docker-compose.yml；docker compose ... up -d 自动用新镜像重建变更过的服务容器。升级前请务必备份 postgres / mysql / es / milvus / minio 对应的数据卷（官方推荐硬件一节已暗示这些组件随容器分发，数据在卷中）。

回滚： 官方未提供一键回滚命令；可基于 Git 通用机制 git checkout <旧版本 tag> 切回上一个版本的 compose 文件，再执行 docker compose ... up -d。因数据卷独立于容器，回滚版本前请确认数据库 schema 兼容性（必要时先按官方 Wiki 备份）。

卸载：

docker compose -f docker-compose.yml -p bisheng down

逐段解释：down 停止并移除 bisheng 项目下全部容器与默认网络（命名卷默认保留）。

若需彻底删除数据卷（此操作永久删除全部知识库、用户、对话历史，请先备份）：

docker compose -f docker-compose.yml -p bisheng down -v

逐段解释：-v 同时删除 Compose 声明的命名卷。

十一、商用许可合规说明

许可证：Apache License 2.0（仓库根目录 LICENSE 文件原文首行：Apache License Version 2.0, January 2004）。
Apache-2.0 允许自由使用、修改、分发与商用；分发时须保留版权声明与许可文本，修改过的文件须标注变更。
官方 README 明确标注「used by a large number of industry leading organizations and Fortune 500 companies」，并提供 Dashboard、DSH 桌面端、Xinchuang 适配等商业版能力作为付费渠道（非强制开源版必须购买）。
第三方组件（ES、Milvus、Onlyoffice、PostgreSQL、MySQL、MinIO 等）按各自开源许可证单独授权，商用前请一并核查其许可条款（例如 Elastic License 对多租户 SaaS 的限制）。