Baserow 技术架构入门指南Django 后端、NuxtJS 前端与核心概念详解【免费下载链接】baserowBuild databases, automations, apps agents with AI — no code. Open source platform available on cloud and self-hosted. GDPR, HIPAA, SOC 2 compliant. Best Airtable alternative.项目地址: https://gitcode.com/GitHub_Trending/ba/baserowBaserow 是一个开源的可视化数据库与无代码应用构建平台其技术体系由「Python Django 后端 NuxtJS/Vue.js 前端」两大组件构成。本指南基于 docs/technical/introduction.md 系统讲解 Baserow 的整体架构、后端 Handler 设计模式、核心概念Workspaces / Applications / Database 插件以及全部官方环境变量帮助你从源码层面理解 Baserow 的模块划分并能在自托管部署中准确配置各项参数。总体架构两个组件、一条 REST APIBaserow 的技术架构由两个主要组件组成后端backend一个 Python Django 应用对外暴露 REST API。它是 Baserow 的核心本身没有用户界面所有持久化状态存储在 PostgreSQL 数据库中。完整的 API 规格见 docs/apis/rest-api.md。Web 前端web-frontend一个面向浏览器的用户界面应用基于 NuxtJS 与 Vue.js 构建通过 REST API 与后端通信。从仓库结构看后端源码位于 backend/src/baserow前端源码位于 web-frontend/modules。这种前后端分离的架构意味着你可以仅部署后端并通过 REST API 完成所有操作也可以完全使用官方前端界面进行可视化操作两者通过同一套 API 契约协作。后端core、api 与 database 三个应用后端包内部由三个应用组成core核心提供认证、Workspace工作空间管理、应用抽象application abstraction等基础能力apiREST API 层以解耦组件的形式实现不是运行 Baserow 的必需部分但强烈推荐使用database以插件形式编写的数据库应用同样不是运行 Baserow 的强制要求——没有它你只拥有带认证、Workspaces 和应用抽象能力的 core。这种「核心 插件」的架构是理解 Baserow 可扩展性的关键数据库功能并不是硬编码进核心而是作为一个默认内置的插件存在。相关的插件机制文档见 docs/plugins/introduction.md。Handler 设计模式API 视图背后的真正执行者如果查看 API 视图层的代码你会发现它们大量使用CoreHandler、TableHandler、FieldHandler等 Handler 类。API 视图本质上只是这些 Handler 的REST API 外壳shell真正干活的逻辑都在 Handler 中。采用这种设计的原因很直接如果将来要实现 Web Socket API、SOAP API 或其他任何类型的 API都可以直接复用在同一个 Handler 之上永远不需要重复编写业务逻辑。同时Handler 也便于在命令行或脚本中直接调用。例如在 Django shell 中创建一个新的 Workspace 只需要几行代码from django.contrib.auth import get_user_model from baserow.core.handler import CoreHandler User get_user_model() user User.objects.get(pk1) workspace CoreHandler().create_workspace(user, nameExample workspace)从源码实现看backend/src/baserow/core/handler.pyCoreHandler.create_workspace并不只是简单地插入一条数据库记录而是一条完整的业务链路首先通过CoreHandler().check_permissions(user, CreateWorkspaceOperationType.type)校验操作权限对应CreateWorkspaceOperationType这一操作类型见 backend/src/baserow/core/operations.py然后创建Workspace记录再以WORKSPACE_USER_PERMISSION_ADMIN权限把当前用户关联为 Workspace 管理员最后通过 Django signal 广播workspace_created事件让实时协作、审计等功能得以响应。同时create_workspace的返回值是新建的WorkspaceUser对象而非 Workspace 本身这一点在使用 Handler 时需要注意。此外CoreHandler中还封装了list_user_workspaces、update_workspace、delete_workspace删除时通过TrashHandler.trash进入回收站而非物理删除、update_settings、权限检查check_permissions等一批方法共同构成 Workspaces 与系统设置的操作入口。从视图到 Handler 的调用链从源码结构看REST API 视图定义在baserow.core.api与baserow.core.views相关的视图模块中它们接收 HTTP 请求、解析参数后把实际工作委托给 Handler再序列化返回结果。前端web-frontend的所有交互最终也都会走这条「浏览器 → REST API 视图 → Handler → PostgreSQL/Redis」的调用链。这意味着无论是调试 API 行为、编写自动化脚本还是排查权限问题Handler 层都是最值得下断点的位置。Web 前端NuxtJS 用户外壳web-frontend 由core和database两个模块组成并包含一些可扩展的基础配置。它本质上是一个运行在浏览器中的、对后端友好的用户外壳user-friendly shell基于 NuxtJS 构建。样式指南Style guide项目中维护了一份包含所有组件的样式指南线上地址https://baserow.io/style-guide本地环境http://localhost:8000/style-guide通过样式指南前端开发者可以快速预览 Baserow 已有的全部 UI 组件保持自定义页面与官方组件库风格一致。核心概念Workspaces 与 ApplicationsWorkspaces工作空间一个 Workspace 可以包含多个 Application。它可以用来代表一家公司并且可以向 Workspace 邀请更多用户——Workspace 内的每个用户都可以访问其中全部应用。实时协作live collaboration让用户无需刷新页面即可立即看到他人的修改。Workspaces 的创建、编辑、删除既可以通过baserow.core.handler.CoreHandler完成也可以通过 REST API 完成。从前端交互看Workspace 对应界面侧边栏顶部的空间列表是用户组织所有数据的最顶层容器。Applications应用Application 是一个更抽象的实体可以被添加到 Workspace 中。默认情况下Baserow 内置了 database 插件其中包含 database 应用。在侧边栏点击「create new」按钮即可为选中的 Workspace 创建新的应用实例点击后会弹出包含所有应用类型的上下文菜单插件可以引入新的应用类型。Applications 同样可以通过baserow.core.handler.CoreHandler和 REST API 创建、编辑和删除。从 Handler 源码可以推断应用类型通过application_type_registry见 backend/src/baserow/core/registries.py注册管理新增应用类型本质上就是向该注册表注册一个新的类型类。Database 插件Baserow 的核心功能载体Database 插件在每一份 Baserow 中都默认安装没有它几乎无法使用这个产品。简而言之它是允许你创建带有电子表格式界面数据库的插件Baserow 的一切都围绕这一概念构建。详细介绍见 docs/technical/database-plugin.md。其核心概念包括表Tables每个 database 应用可包含多张表。表中的列在 Baserow 中被称为字段fields每张表在 PostgreSQL 数据库中都有独立的 schema 表示。baserow.contrib.database.table.handler.TableHandler负责表的增删改查并且可以通过table.get_model(attribute_namesTrue)动态生成 Django model 直接查询数据。字段Fields字段是表的列定义只接受特定数据类型如数字字段可限制小数点后位数。新增字段时数据库中会同步新增一列列名形如field_{id}。字段操作由baserow.contrib.database.fields.handler.FieldHandler负责。默认内置的字段类型包括text单行文本、long_text多行文本、number数字可负、可小数、boolean布尔、date日期EU/ISO/USA 格式可含 am/pm 时间。字段类型可以通过插件扩展见 docs/plugins/field-type.md。视图Views视图定义了表数据面向用户的展示方式默认包含grid网格视图类型以电子表格式界面呈现。每张表可以有多个视图且每个视图拥有独立设置例如视图 A 调整列宽不会影响视图 B。视图操作由baserow.contrib.database.views.handler.ViewHandler负责视图类型同样可通过插件扩展见 docs/plugins/view-type.md。行Rows行是表数据本身接受的取值取决于表字段定义数据存储于数据库中的表示表。以下示例展示了通过 Python shell 插入一行数据也可通过 REST API 达到同样效果from django.contrib.auth import get_user_model from baserow.contrib.database.table.models import Table from baserow.contrib.database.fields.handler import FieldHandler from baserow.contrib.database.rows.handler import RowHandler User get_user_model() user User.objects.get(pk1) table Table.objects.get(pk10) name FieldHandler().create_field(user, table, text, nameName) price FieldHandler().create_field(user, table, number, namePrice) row RowHandler().create_row(user, table, { ffield_{name.id}: Smartphone, ffield_{price.id}: 300 }) model table.get_model() rows model.objects.all() print(rows[0].name) print(rows[0].price) # Which will result in: # Smartphone # 300上述调用链印证了 Handler 设计模式的复用价值FieldHandler、RowHandler与视图层的调用方式完全一致均为「校验权限 → 执行业务 → 广播 signal」。环境变量完整参考配合默认 settings 与 configBaserow 支持以下环境变量。这些变量主要在后端配置 backend/src/baserow/config/settings/base.py 中读取是自托管部署的核心配置入口。数据库连接环境变量默认值说明DATABASE_NAMEbaserowPostgreSQL 数据库名DATABASE_USERbaserowPostgreSQL 用户名DATABASE_PASSWORDbaserowPostgreSQL 密码DATABASE_HOSTdbPostgreSQL 服务器主机名DATABASE_PORT5432PostgreSQL 服务器端口在 base.py 的源码中可以看到如果设置了DATABASE_URL则会优先使用dj_database_url.parse解析整条连接串否则才逐个读取上述DATABASE_*变量。因此两种配置方式二选一即可。此外源码还支持DATABASE_READ_*_URL/DATABASE_READ_*_NAME形式的只读副本read replica配置会通过DATABASE_ROUTERS [baserow.config.db_routers.ReadReplicaRouter]进行读写分离详见 docs/development/read-replicas.md。Redis 连接环境变量默认值说明REDIS_HOSTredisRedis 服务器主机名REDIS_PORT6379Redis 服务器端口REDIS_USER空Redis 用户名REDIS_PASSWORD空Redis 密码REDIS_PROTOCOLredisRedis 协议可选redis或redissTLSREDIS_SSL_CERT_REQSrequiredSSL 证书要求可选required、optional、noneREDIS_SSL_CA_CERTS空CA 证书文件路径Redis 在 Baserow 中承担多重职责缓存settings 缓存、动态生成的模型缓存、Celery 任务队列、Channels 实时通信CHANNEL_LAYERS 使用channels_redis.core.RedisChannelLayer。从 base.py 可以看出这些变量最终会拼接成一条REDIS_URL再被CACHES、CELERY_BROKER、CHANNEL_LAYERS等配置共享引用。邮件SMTP环境变量默认值说明EMAIL_SMTP空提供非空值即启用 SMTP 邮件EMAIL_SMTP_HOSTlocalhostSMTP 服务器主机名EMAIL_SMTP_USE_TLS空提供非空值即通过 TLS 连接 SMTPEMAIL_SMPT_USE_TLS空EMAIL_SMTP_USE_TLS的旧拼写历史兼容EMAIL_SMTP_PORT25SMTP 服务器端口EMAIL_SMTP_USER空SMTP 用户名EMAIL_SMTP_PASSWORD空SMTP 密码FROM_EMAILno-replylocalhost平台发送邮件如密码找回邮件的「发件人」地址需要特别说明的是EMAIL_SMPT_USE_TLSEMAIL_SMTP_USE_TLS最初被错误拼写为EMAIL_SMPT_USE_TLS该问题在 MR #247 中已被修复。为了兼容仍在使用旧变量名的环境EMAIL_SMPT_USE_TLS目前依然受支持但强烈建议使用最新版本的正确变量名因为旧拼写可能在将来被移除。源码层面base.py正是通过bool(os.getenv(EMAIL_SMTP_USE_TLS, )) or bool(os.getenv(EMAIL_SMPT_USE_TLS, ))同时兼容新旧两种写法并在同时设置EMAIL_SMTP_USE_SSL与EMAIL_SMTP_USE_TLS时给出警告。另外EMAIL_SMTP为空时整个 SMTP 分支不会启用邮件功能保持禁用状态。前后端 URL 与文件下载环境变量默认值说明PUBLIC_BACKEND_URLhttp://localhost:8000后端对外可访问 URL。开发环境为http://localhost:8000若将端口改为 9000 则为http://localhost:9000浏览器可直接访问PRIVATE_BACKEND_URLhttp://backend:8000不仅浏览器web-frontend 服务器也需要向后端发 HTTP 请求。它可能无法访问PUBLIC_BACKEND_URL或存在更直接的路由例如容器与容器之间而非经过公网。开发环境中后端容器可通过backend主机名访问因容器内服务同样运行在 8000 端口故私有后端 URL 应为http://backend:8000PUBLIC_WEB_FRONTEND_URLhttp://localhost:3000web-frontend 对外可访问 URL开发环境为http://localhost:3000端口可任意修改浏览器可访问DOWNLOAD_FILE_VIA_XHR0设为1强制下载链接通过 XHR 请求下载文件以绕过无法以其他方式覆盖的Content-Disposition: inline。若文件存储在其他源origin下还需在服务器上添加 CORS 头BASEROW_DISABLE_GOOGLE_DOCS_FILE_PREVIEW空设为true或1可禁用 web-frontend 中的 Google Docs 文件预览PUBLIC_BACKEND_URL与PRIVATE_BACKEND_URL的区分是部署中的常见易错点前者服务于浏览器后者服务于前端服务器内部请求两者在容器化部署如 docker-compose中通常是不同的主机名与网络路径。数据导入与回收站环境变量默认值说明INITIAL_TABLE_DATA_LIMIT未设置初始表数据量限制。例如设置为100则无法导入超过 100 行的 CSV 文件BASEROW_MAX_IMPORT_FILE_SIZE_MB512允许导入的最大文件大小MBHOURS_UNTIL_TRASH_PERMANENTLY_DELETED72回收站中的项目在多少小时后被永久删除INITIAL_TABLE_DATA_LIMIT在 base.py 中的实现为仅在环境变量存在时才读取并转为int因此默认状态下不限制。HOURS_UNTIL_TRASH_PERMANENTLY_DELETED的默认值72在源码中写作os.getenv(HOURS_UNTIL_TRASH_PERMANENTLY_DELETED, 24 * 3)即 3 天回收站机制由baserow.core.trash.handler.TrashHandler实现这也是 Handler 层代码中删除 Workspace 时先进入回收站而非直接物理删除的原因。实时协作环境变量默认值说明DISABLE_ANONYMOUS_PUBLIC_VIEW_WS_CONNECTIONS空设为true时禁止向公开共享的视图发送实时事件WebSocket该变量对应源码 base.py 中的DISABLE_ANONYMOUS_PUBLIC_VIEW_WS_CONNECTIONS布尔配置用于需要严格控制匿名实时数据流量的部署场景。Baserow 的实时协作底层依赖 WebSocket 与 Redis Channel Layer相关机制可进一步阅读 docs/technical/websockets.md 与 docs/technical/realtime-presence.md。进一步阅读Database 插件深入指南表、字段、视图、行的详细概念与代码示例REST API 规格全部 API 端点与请求/响应格式WebSocket API实时协作的通信协议插件开发文档应用类型、字段类型、视图类型如何通过插件扩展权限指南Actor / Operation / Context 权限模型与 Permission Manager 机制运行与部署文档基于上述环境变量的完整配置说明【免费下载链接】baserowBuild databases, automations, apps agents with AI — no code. Open source platform available on cloud and self-hosted. GDPR, HIPAA, SOC 2 compliant. Best Airtable alternative.项目地址: https://gitcode.com/GitHub_Trending/ba/baserow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考