NocoBase零代码平台部署教程：用Docker Compose搭建博客管理后台

这次我们来看一个开源零代码平台：NocoBase。很多人搭建内部系统、管理后台、业务工具，第一反应是买商业 SaaS 或者请人定制开发。实际上，如果你只需要在浏览器里定义数据表、拖拽出页面、设置权限，然后有一个还能对外开放 API 的后端服务，NocoBase 会比传统开发快很多。

这篇是 NocoBase 系列教程的第 2 篇。上一篇主要讲了 NocoBase 的整体定位、模块组成和它区别于其他零代码平台的特点。这篇直接进入正题：从零开始安装部署，然后用一个“博客系统”作为真实案例，把数据表设计、页面配置、权限管理、API 调用和批量操作全部跑一遍。看完之后，你就能判断这个开源零代码平台适不适合接到自己的项目里。

先给结论：NocoBase 是一个可私有化部署的开源零代码平台，前后端分离，核心能力是“数据模型 + 区块化页面 + 角色权限 + RESTful API”。它不像很多国外低代码平台那样强制连云端，也没有把功能锁在商业版里。你要做的只是准备一台有 Docker 的服务器或开发机，然后把服务跑起来，剩下的工作在浏览器里完成。整个教程我会用 Linux + Docker Compose 的方式部署，并且用“文章管理”这个小博客案例，带你走通从建表到发布的完整链路。

1. 核心能力速览

在开始安装之前，先把 NocoBase 的关键信息放在一张表里，方便你判断是否值得继续往下看。

这里要特别说明一个点：NocoBase 的“零代码”不等于“空壳”。它的重点是把数据模型和页面交互做成可视化操作，让非开发人员也能搭出可用的管理系统。但与此同时，它保留了插件机制和标准 API，开发人员拿到手之后依然可以二次扩展。对团队来说，这意味着业务人员可以自己调整字段和布局，技术人员专注于插件、权限和集成逻辑。

2. 适用场景与使用边界

NocoBase 最适合的场景是“有一定数据关系、需要多人协作、需要后台管理的内部系统”。举几个常见例子：

• 内容管理后台：文章、标签、分类、作者审核管理。
• 进销存与订单管理：商品表、订单表、库存表、客户表之间的关联。
• 项目协同工具：项目、任务、负责人、里程碑、日志表。
• 运营数据平台：线索表、跟进记录、报表看板。

它的优势在于，当业务字段和页面布局频繁调整时，你不需要每次都改代码重新发布。管理员直接在页面上加一个字段、拖一个报表区块，就能在几分钟内看到新版本。

但也要清楚边界。NocoBase 不适合用来做高并发 C 端应用，也不适合实现极其复杂的业务逻辑和前端交互相。比如你要做一个给海量用户实时使用的社交平台，或者做一个强交互的数据可视化大屏，这些场景用原生开发或专业前端框架会更好。零代码平台的定位是“快速搭建业务后台和管理工具”，而不是“替代所有编程开发”。

另外，在使用边界上还要注意合规和授权问题。因为是私有化部署，数据存放在你自己的服务器中，你需要自行负责数据备份、访问权限和隐私保护。如果系统里包含员工信息、客户信息或版权内容，务必做好角色权限最小化配置，同时在对外访问时加上 HTTPS 和访问限制。

3. 部署前需要明确几个概念

安装 NocoBase 之前，建议你先理解几个核心概念，后面操作时不会懵。

第一个是“数据表”。NocoBase 里的数据表对应数据库中的一张表，但你可以直接在后台页面中创建，不需要手写 SQL。每一张表可以配置字段，字段类型包括单行文本、多行文本、数字、日期、单选、多选、关联、附件、JSON 等。

第二个是“区块”。区块是页面上的可视化组件，比如表格区块、表单区块、详情区块、日历区块、图表区块。你可以把一个数据表拖到页面中，配置成列表展示；也可以放一个表单区块，用于新增或编辑记录。

第三个是“角色权限”。NocoBase 内置了权限系统，可以创建不同角色，比如管理员、编辑、访客。每个角色可以控制某个数据表的查看、创建、更新、删除权限，甚至可以做字段级别的权限控制。

最后一个概念是“数据源”。默认情况下，你在 NocoBase 里创建的数据表会存在它自己的主数据库中。它还支持接入外部数据源，也就是说你能把已有的业务数据库作为 NocoBase 的数据源来配置页面。这个功能对老系统改造很有价值，不过本次教程先用默认主数据库就够了。

4. 环境准备与前置条件

本次安装推荐使用 Docker Compose 方式，因为它把 NocoBase 的后端、前端打包在一个容器里，把数据库拆到另一个容器中，结构清晰、卸载方便。你需要准备以下环境：

• 一台 Linux 服务器，或者本地 Linux / macOS 开发机。Windows 用户建议使用 WSL2。
• 安装 Docker 和 Docker Compose 插件。
• 规划一个空闲端口，教程里使用 13000 作为演示端口，也可以按需修改。
• 如果你有域名，建议提前把域名解析到服务器 IP，后续配置 HTTPS 更方便。没有域名就直接用 IP 访问。

确认 Docker 环境是否正常，可以先执行两条命令：

docker --version docker compose version

如果版本命令都能正常输出，说明 Docker 环境已经就绪。接下来确认磁盘空间。NocoBase 的镜像加上数据库初始化数据，预留 10G 以上磁盘空间会更从容，生产环境请根据业务数据量另行评估。

5. NocoBase 安装部署与启动

这里有两条安装路径。官方推荐的是 Docker Compose 方式，适合绝大多数人；源码方式适合需要深度定制插件或调试后端逻辑的开发者。这里重点讲 Docker Compose。

5.1 使用官方仓库的 Docker 模板

创建一个项目目录，然后从 GitHub 拉取 NocoBase 官方仓库，仓库中的 docker 目录内自带编排模板：

mkdir -p ~/nocobase-demo cd ~/nocobase-demo git clone https://github.com/nocobase/nocobase.git cd nocobase/docker cp .env.example .env

编辑.env文件，重点确认几个配置项。如果你的服务器端口 13000 被占用，可以把APP_PORT改成其他端口。数据库相关配置可以先用默认值，生产环境建议把密码改成强密码：

# 应用端口 APP_PORT=13000 # 数据库类型：postgres / mysql / sqlite DB_DIALECT=postgres DB_HOST=db DB_PORT=5432 DB_DATABASE=nocobase DB_USER=nocobase DB_PASSWORD=nocobase

保存后启动：

docker compose up -d

首次启动会拉取 NocoBase 镜像和数据库镜像，耗时取决于网络情况。看到容器状态为 running 后，说明服务已经起来了。

5.2 自定义 docker-compose.yml 方式

如果你不想克隆整个源码仓库，也可以直接写一个精简的docker-compose.yml。下面的配置是一个通用模板，实际部署时请以 NocoBase 官网最新文档为准，必要时替换镜像标签和数据库版本：

services: app: image: nocobase/nocobase:latest ports: - "13000:80" environment: - APP_KEY=please-change-to-your-own-key - DB_DIALECT=postgres - DB_HOST=db - DB_PORT=5432 - DB_DATABASE=nocobase - DB_USER=nocobase - DB_PASSWORD=nocobase volumes: - ./storage:/app/nocobase/storage depends_on: - db restart: always db: image: postgres:16 environment: - POSTGRES_DB=nocobase - POSTGRES_USER=nocobase - POSTGRES_PASSWORD=nocobase volumes: - ./storage/db:/var/lib/postgresql/data restart: always

在这个配置中，./storage目录会同时存放 NocoBase 的附件、备份文件和数据库数据。最核心的一个环境变量是APP_KEY，它是应用密钥，生产环境一定要改成随机长字符串，否则会话和令牌存在安全风险。DB_DIALECT=postgres表示使用 PostgreSQL 数据库。如果你更熟悉 MySQL，也可以把DB_DIALECT改成mysql，并调整db服务的镜像和数据库连接变量。

启动命令同样是：

docker compose up -d

5.3 检查启动日志

启动之后，可以查看容器日志，确保没有报错：

docker compose logs -f app

如果日志中出现了类似“Application is running”或“Web server started”的提示，说明应用已经启动。此时访问：

http://服务器IP:13000

如果是在本地开发机上部署，访问：

http://localhost:13000

浏览器打开后，应该会进入 NocoBase 的初始化安装界面。

6. 初始化：创建管理员账号与系统设置

首次访问 NocoBase，不会直接看到功能页面，而是先进入安装向导。这一步需要你创建一个管理员账号，也就是之后登录后台用的账号密码。

页面上的关键字段通常包括管理员邮箱、密码、确认密码，以及系统标题等。填写完成后，点击安装或初始化按钮，系统会自动创建数据库表结构并初始化基础数据。

需要注意几个细节：

• 管理员邮箱建议使用你日常可访问的邮箱，密码不要使用弱口令。
• 如果初始化过程中卡住，优先检查docker compose logs app的输出。最常见的问题是数据库连接失败，比如DB_PASSWORD和数据库容器密码不一致。
• 初始化完成后，页面会跳转到登录界面。输入刚才创建的管理员邮箱和密码，就能进入 NocoBase 后台。

登录成功后，你会看到左侧的菜单区、顶部的工具栏和中间的内容区。默认情况下左侧可能只有“UI 编辑器”和“设置”等少量菜单。这里不要着急，后面我们按博客案例一步步搭建。

7. 博客案例：从零搭建一个内容管理后台

这个案例的目标是搭建一个简单的博客管理后台，能实现文章发布、列表展示、状态管理和后台查看。我们用 NocoBase 一个早上就能搭完，不需要写任何前端代码。

7.1 创建“文章”数据表

进入后台后，先创建业务数据表。点击顶部或左侧的“数据表管理”入口，新建一个数据表，命名为articles，中文名称可以写成“文章”。

然后为这张表添加字段，先保持最小可用：

在 NocoBase 的字段配置界面中，可以直接添加这些字段。选择“单行文本”时，可以勾选“必填”约束；选择“单选”时，手动录入“草稿”和“已发布”两个选项；选择“数字”时，可以设置默认值0。

保存数据表后，你可以在“数据表管理”中看到这张表的所有字段。如果之后发现字段不够，直接在表结构上新增字段即可，不需要进行任何数据库迁移操作。

7.2 配置后台菜单页面

数据表创建好之后，回到页面管理，把左侧菜单和页面区块配置起来。这里目标是做一个“文章列表页”，用来展示所有文章记录。

操作步骤如下：

1. 新建一个菜单项“文章管理”。
2. 进入该菜单的编辑器模式。
3. 从数据区块中选择“表格区块”，数据表选择articles。
4. 把表格区块拖入页面主体区域。
5. 在表格区块的字段设置中，选择显示 title、status、published_at、views 等字段。

保存页面后，左侧菜单就会出现“文章管理”，点击之后就能看到当前数据表里的文章列表。因为还没有数据，表格是空的，此时可以顺手测试新增记录：

1. 在页面右上角添加“创建表单”按钮，或直接配置一个“创建表单”区块。
2. 填上标题、正文、状态等字段。
3. 提交后刷新列表，看记录是否出现在表格中。

这一步能验证最常见的“新增 + 列表展示”链路。

7.3 配置访客与编辑角色

博客场景里，通常有两种角色：一种是维护内容的编辑，一种是只需要看内容的访客。NocoBase 的权限体系可以这样配置。

在“设置 -> 角色与权限”中，默认有管理员角色。管理员拥有所有权限，不需要额外配置。然后新建一个“编辑”角色，授予articles表的查看、创建、更新、删除权限；新建一个“访客”角色，只授予查看权限。

如果希望访客只能看到“已发布”的文章，可以进一步设置数据范围。数据范围条件选择status等于已发布。这样不同角色登录后，看到的列表内容是不同的。

当然，实际项目中为访客创建登录账号的场景比较少见，更多时候你可能会通过 API 对外提供文章列表接口，然后在访客权限中做好数据隔离即可。

7.4 添加标签表并建立关联

现在把案例稍微升级一下，给文章加上“标签”能力。先新建一张tags表，字段只需要一个name（单行文本）。

然后在articles表中增加一个“关联字段”，类型选择“多对多”，关联到tags，表示一篇文章可以有多个标签，一个标签也可以属于多篇文章。保存后，在文章表单里你就能看到“标签”选择控件，可以直接勾选已有标签。

这个案例可以很好地证明 NocoBase 的关系字段能力。对后台系统来说，订单和客户、项目和成员之间大量存在这种关联关系。用零代码平台搭建时，不需要写外键和联表查询，配置界面里点几下就完成了。

7.5 测试完整发布流程

完成以上步骤后，建议完整跑一遍博客发布的流程：

1. 使用管理员账号登录后台。
2. 进入“文章管理”页面，点击新建文章。
3. 填写标题、正文，选择状态为“草稿”。
4. 提交后，确认列表中出现一条草稿记录。
5. 再次编辑这条记录，把状态改成“已发布”，设置发布时间。
6. 刷新列表，确认记录状态和发布时间都已更新。

如果每一步都顺利，说明这个博客案例的核心链路已经跑通。接下来可以把这些数据通过 API 暴露给外部访问。

8. 接口 API 调用与批量操作

NocoBase 自带 RESTful API，这是它作为“后端平台”非常关键的亮点。页面上的所有操作，底层都可以通过 API 完成。下面给出通用调用方式和示例，具体路径和字段名请以实际部署后系统内的 API 文档为准。

8.1 查看 API 文档

部署完成后，可以在 NocoBase 后台找到 API 文档入口，里面会列出当前所有集合的接口。API 路径通常类似：

GET /api/articles:list POST /api/articles:create PUT /api/articles:update DELETE /api/articles:destroy

这里的articles对应你创建的数据表名。因为articles是多对多关联了tags，所以创建文章时你还可以在请求体中带上标签关联参数。

8.2 curl 调用示例

先用管理员账号登录，获取访问令牌。登录接口通常是 POST 请求，提交邮箱和密码，实际字段名以 API 文档为准：

curl -X POST http://127.0.0.1:13000/api/auth/signin \ -H "Content-Type: application/json" \ -d '{ "email": "admin@example.com", "password": "your-password" }'

登录成功后会返回一个 token。之后请求业务接口时，在请求头里带上这个 token：

curl -X POST http://127.0.0.1:13000/api/articles:create \ -H "Authorization: Bearer TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "NocoBase 博客案例", "content": "这是一篇通过 API 创建的文章。", "status": "已发布" }'

创建成功之后，再调用列表接口，确认数据已经写入：

curl "http://127.0.0.1:13000/api/articles:list?pageSize=10&page=1" \ -H "Authorization: Bearer TOKEN"

如果返回的 JSON 中包含刚才创建的文章记录，说明 API 链路是通的。

8.3 Python 批量任务示例

后端集成的典型场景是批量导入数据。比如你有一批历史博客文章需要迁移到新系统，可以用 Python 脚本调用 API，把文章批量写入。

下面给出一个通用模板，你需要根据实际接口路径和字段名调整：

import requests BASE_URL = "http://127.0.0.1:13000/api" TOKEN = "your-token" headers = { "Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json" } articles = [ {"title": "文章标题1", "content": "正文1", "status": "已发布"}, {"title": "文章标题2", "content": "正文2", "status": "草稿"}, {"title": "文章标题3", "content": "正文3", "status": "已发布"} ] for article in articles: resp = requests.post( f"{BASE_URL}/articles:create", json=article, headers=headers, timeout=30 ) if resp.status_code == 200: print(f"创建成功: {article['title']}") else: print(f"创建失败: {article['title']}, {resp.text}")

如果你每天都有大量新内容要写入，可以把这个脚本挂到定时任务里，或者结合 NocoBase 的工作流插件，在表单提交后自动触发后续处理。

8.4 批量更新与分批处理

批量导入几百条数据时，不要一次性把所有记录上传。更稳妥的做法是分批处理，每批 50 条或 100 条。写入前先调用列表接口查询是否已存在相同标题，避免重复导入。对失败的请求，要捕获异常并记录到日志中，方便后续重试。

批量操作的另一个常用场景是批量更新状态。比如把所有“草稿”文章统一改为“已发布”，可以先用列表接口查出符合条件的记录 id，再逐条调用更新接口。也可以在页面表格中先筛选，然后选择多条记录进行批量操作，NocoBase 页面本身就支持这个能力。

9. 资源占用与性能观察

NocoBase 部署后，资源占用需要以自己的服务器环境为准。这里重点讲观察方法和影响性能的因素，而不是给出某个固定数值。

先看 Docker 容器状态：

docker ps docker stats

docker stats会实时显示每个容器的 CPU、内存和网络占用。观察时建议分两个维度看：空闲状态下的基础占用，以及业务操作时的峰值占用。如果你同时在 NocoBase 后台编辑页面、批量导入数据，内存占用会明显上升。

影响 NocoBase 性能的主要因素有几个：

• 数据库类型和配置。PostgreSQL 在复杂查询和并发场景下表现更稳定。
• 单表数据量。当文章表、日志表数据量达到百万级后，列表查询会变慢，需要合理使用筛选条件和数据库索引。
• 附件和文件数量。NocoBase 支持附件上传，附件会存储在 storage 目录中。附件过多会影响磁盘空间，建议定期清理。
• 并发访问量。如果对外提供 API 服务，需要考虑网关层和容器资源的扩展。对于内部管理系统，常规并发量下不需要额外调优。

如果发现容器内存长期过高，可以先检查是不是附件读取或日志输出过大。给 Docker 容器设置资源限制也是一种办法，在docker-compose.yml中为服务配置 mem_limit，避免单个容器耗尽整台服务器内存。

10. 常见问题与排查方法

实际操作中，大多数人会遇到的问题集中在安装、登录和数据库连接上。这里整理成表格，方便你快速定位。

如果遇到不在表格里的问题，第一步永远是看日志：

docker compose logs -f app docker compose logs -f db

日志里通常会有明确报错。零代码平台的问题大多集中在环境变量配置和网络端口上，很少需要深入代码调试。

11. 最佳实践与使用建议

把 NocoBase 用到生产环境之前，建议先建立一套自己的使用规范，避免系统越用越乱。

第一，数据表命名从一开始就要规范。数据表名使用小写英文字母和下划线，业务名称写在中文备注里。比如articles表中文名“文章”，tags表中文名“标签”。一旦系统里几十张表之后，没有规范命名会很难维护。

第二，字段权限和角色权限要最小化。能只读就不开放编辑，能指定数据范围就不给全部数据。NocoBase 支持字段级权限，比如访客可以看到文章标题，但不能看到文章编辑人的内部备注。这个能力在生产环境非常实用。

第三，把storage目录纳入备份计划。NocoBase 的附件、上传文件、数据库 volume 都在这个目录下。建议每天定时打包备份到异地，或者至少使用云磁盘快照。

第四，环境区分。开发环境、测试环境、生产环境建议分开部署。不要在生产环境里直接做页面布局调整。NocoBase 的页面配置是存在数据库里的，开发环境改完可以导出备份，再恢复到测试环境验证。

第五，对外暴露服务前先做安全加固。如果你要通过外网访问管理后台，务必加 HTTPS，更换默认端口，设置强密码。如果 API 只给内部系统调用，可以在网关层限制来源 IP，减少不必要的攻击面。

第六，注意数据合规。如果系统涉及用户隐私数据，要严格遵守网络安全和个人信息保护相关要求。不要随意导出含个人信息的表格，也不要授权给无关人员访问。涉及版权素材时，确认素材来源合法。

12. 总结与下一步

NocoBase 这个开源零代码平台，最值得尝试的点是“数据表、页面区块、权限、API”闭环非常完整。你不需要写前端代码，就能做出一个可用的业务后台；需要数据集成时，RESTful API 又给了很大的自由度。

这篇教程建议你最先验证三件事：第一，用 Docker Compose 正常启动并创建管理员账号；第二，创建文章表和标签表，并在页面中配置表格区块；第三，调用 API 创建一个新记录并查询成功。如果这三步都能完成，说明你已经可以把 NocoBase 当作一个落地工具来使用了。

最容易踩的坑集中在数据库连接配置和容器数据持久化上。数据库密码不一致会导致初始化失败，数据库容器没有挂载 volume 会导致重启后数据丢失。安装时不要跳过这些细节，生产环境一定要确认 storage 和数据库数据卷都落在宿主机磁盘上。

后续可以继续扩展的方向包括：接入外部业务数据源，把已有的 MySQL 数据库接到 NocoBase 上配置页面；使用工作流插件，实现审批、消息通知和定时任务；基于现有业务表构建更多图表看板，让管理层直接看到关键指标。也可以进一步研究 NocoBase 的插件机制，开发自己的业务插件。

这篇到这里，NocoBase 安装和博客案例已经全部跑通。下一篇可以聚焦“数据源接入与企业内部系统迁移”，把零代码平台真正用到一个接近生产环境的项目中去。建议收藏备用，后面部署和排错时可以直接翻出来对照。