Celerp 完全指南：用本地优先与事件账本搭建可扩展的业务系统
ERP（企业资源计划）软件常常在两个方向之间拉扯：一端是功能齐全、部署和定制成本也很高的大型系统；另一端则是由表格、SaaS 和脚本拼接出来的业务流程。Celerp 选择了另一个值得开发者关注的方向：把本地部署的业务管理应用、Python 扩展机制与不可变事件账本放进同一套系统，尝试提供可自行承载、可逐步改造的 ERP 基础。
它的定位要先说清楚。Celerp 是一款免费的本地/自托管业务管理应用，覆盖库存、联系人、单据、会计、报表、制造等常见业务领域。项目仍处于早期，适合将其作为可评估、可试验和可二次开发的技术底座，而不应在没有完成领域验证前，把它当作已经能替换全部核心系统的成熟产品。
许可证先行：它不是“整个项目完全开源”
评估 Celerp 时，最不应模糊的是交付层次和许可证。项目核心采用 BUSL-1.1（Business Source License 1.1），默认业务模块采用 MIT；官方 UI、文档/PDF 输出和云端 AI 层则属于专有部分。
因此，“仓库可访问”或“可以免费下载、自托管”都不等于整个产品都是开源软件。计划把它嵌入商业 SaaS、向客户再分发、改造官方界面，或接入云端 AI 能力的团队，应分别核对核心、模块和附加层的许可边界。对于重视供应链治理的组织，也应把依赖许可、部署模型和最终交付方式放进同一份审查清单。
这种分层并非一定是缺点：MIT 模块降低了业务扩展的复用门槛，而维护者可为部分产品层保留商业化空间。但代价是技术负责人不能只看“能否运行”，还要在原型阶段确认未来的使用方式是否落在许可允许的范围内。
架构重点：事件账本不是普通的更新表
Celerp 后端使用 Python 和 FastAPI，界面使用 FastHTML，并以 PostgreSQL 为数据服务。它的关键设计是事件溯源：业务变化以不可变账本事件记录，再由查询投影（query projections）生成供界面、报表或 API 读取的状态。
与直接把库存余额或应收金额覆盖写入一张“当前状态”表相比，事件模型保留了状态如何形成的轨迹。例如，库存数量不只是最后的数字；在领域规则设计正确的前提下，它可以由入库、出库、更正等一系列业务事件推导。这样的模型有利于审计、追查异常、重建报表视图，以及让不同读取模型服务于不同业务场景。
但事件溯源不意味着实现更简单，至少要正面处理五个问题：
- 事件语义稳定性：事件名称和字段被持久化后，会成为长期兼容性契约。
- 投影重建成本：投影逻辑变更时，需要能重放事件、重建读取模型并控制执行时间。
- 一致性边界：写入完成与读取模型更新之间可能存在间隔，界面和集成方不能假定每次读取都立即反映最新事件。
- 更正流程：不可变并不表示不能纠错，而是应通过补偿、冲销或明确的更正事件表达。
- 恢复演练：备份不能只看数据库文件能否还原；还要验证事件序列、投影和外部附件是否重新一致。
所以，Celerp 的事件账本更适合真正看重业务可追溯性、且愿意维护领域模型的团队。若流程很简单，或团队无法承担投影维护和迁移工作，传统 CRUD 架构仍可能更直接。
先在隔离环境跑通安装与启动
Celerp 提供 Python 包和命令行初始化流程。默认初始化会设置数据库、运行迁移并启动应用；如果机器上没有现成的 PostgreSQL，项目会使用打包的数据库。已有 PostgreSQL 时，可以显式传入 asyncpg 连接 URL。
pip install celerp celerp init celerp init --db-url postgresql+asyncpg://USER:PASSWORD@HOST:5432/DBNAME celerp init --no-start celerp start pytest tests/
启动后可通过 http://localhost:8080 访问。评估阶段应使用隔离数据库和最小化样本数据，不要一开始就接入真实财务数据，更不要把本地端口直接暴露到公网。需要远程访问时，应由已有的反向代理、TLS、认证、网络隔离和备份体系承接；上线前还应完成权限审查、日志留存、数据库恢复、依赖版本固定与升级回滚演练。
模块化扩展：把业务规则写成 Python 包
Celerp 将业务域拆分为模块，现有模块包括库存、联系人、单据、会计、报表、订阅、制造、标签和行业预设。模块可以作为 Python 包放进 modules/ 目录，增加自己的表、API 路由和 UI 页面，而不必先 fork 整个项目。
这给有内部流程或垂直行业需求的团队留下了更明确的扩展入口。一个合理的起点不是立刻重写采购、财务和库存，而是选取边界清晰的小能力，例如设备维修单、质检记录、项目成本归集，或某个渠道的订单同步。自定义模块应优先复用已有领域对象和事件模式，避免绕开账本模型又形成一套无法追溯的数据流。
模块开发至少应建立几条工程边界：把领域规则、数据访问、HTTP 路由和页面呈现分开；为事件定义版本策略；为投影重建、重复投递和失败补偿写测试；将外部调用设计为可重试、可观测的边界；升级 Celerp 前在副本数据库验证迁移与自定义模块的兼容性。
这种可扩展性的代价也很清楚：团队需要具备 Python、PostgreSQL、业务建模和基础运维能力。如果组织只希望通过配置快速上线，或者无法长期维护自定义代码，那么成熟的托管 ERP 可能是风险更低的选择。
功能清单不是选型结论，先验证一条真实业务链
Celerp 列出库存、发票与采购订单、会计、制造、CRM、报表等能力。这让它有机会成为统一业务工作台：同一套业务实体可以在库存流转、销售单据和财务记录之间关联起来。但“模块存在”与“适合某家企业”是两件事，尤其是财税、制造和行业合规场景。
选型时，建议用一笔完整的采购、入库、销售、开票和收款流程做验证，并明确库存计价、退货、负库存、批次或序列号等规则是否符合需求。单据模板、编号、权限和审批节点也应按内部控制要求检查。对账、期末和税务处理必须由熟悉本地规则的人员确认；对接电商、支付、仓储或会计系统时，则应先验证 API 边界、失败处理和重试策略。
这样做的目的不是证明系统“功能很多”，而是在投入扩大前尽早发现领域规则和现有流程的错位。
数据、权限与运维：本地部署不等于默认安全
“数据留在自己的机器或网络中”是本地优先架构的重要价值，但它不是自动获得安全性的同义词。Celerp 的 README 明确说明应用可作为本地服务器运行，团队成员可经局域网连接。因此在试点中，首先要明确谁可以访问实例、谁能创建或修改业务记录、谁可以导出数据，以及管理员账号和数据库凭据由谁保管。
权限设计应按职责而不是按“方便”划分。实际业务里，录入采购、调整库存、确认收款、查看报表和管理用户通常不应由同一个角色无限制完成。Celerp 列出了多级角色权限；团队仍应以自己的职责分离要求做测试：低权限账号是否确实无法进入不应访问的页面或接口，敏感导出是否受控，离职或岗位变更后的账号如何撤销。不要仅根据界面是否隐藏按钮来判断权限已经生效。
数据库备份也不能停留在“每天复制一次文件”。一个最小但有意义的演练应包含：在测试环境写入可识别的业务样本；执行备份；恢复到隔离实例；确认应用能启动；核对关键单据、事件记录和报表读取是否仍能对应。若接入附件、邮件、外部存储或第三方 API，还要明确这些数据是否包含在恢复边界内。恢复目标、保留周期、演练频率和负责人都应在试点时写下来，而不是等业务依赖加深后再补。
对于需要跨网访问的部署，建议把暴露面控制在现有基础设施内：由经过维护的网关承担 TLS 和认证，在网络层限制来源，并把应用、数据库与备份存储的访问权限分开。这样做并不是 Celerp 特有要求，而是任何将业务和财务数据放入自托管应用时都应满足的最低工程纪律。
怎样把“可扩展”变成可维护的交付
Python 模块目录给了团队扩展入口，却不会自动保证扩展长期可维护。自定义模块在第一次提交前，就应该有独立的版本号、变更记录、依赖锁定方式和安装说明。尤其是涉及外部同步的模块，应把网络调用放在清晰的适配层，记录请求的关联标识、失败原因和重试结果；否则出了重复单据或数据不一致问题时，很难判断是业务规则、网络抖动，还是人工重复操作造成的。
可以把一个自定义模块拆成四类可测试内容。第一类是纯领域规则，例如什么条件下允许创建某种业务记录；第二类是事件和投影，验证相同事件序列是否产生预期读取状态；第三类是 API 或界面边界，验证参数校验和权限；第四类是外部集成，使用可控的模拟端点覆盖超时、重复回调和部分失败。这样的分层测试比只点击几次页面更能暴露升级与重放时的问题。
还应避免让 AI 编码工具直接对生产数据库或生产模块做未经审查的修改。AI 可以辅助生成模块骨架、测试用例或文档，但数据迁移、权限更改、会计规则和事件格式应进入正常的代码审查与测试流程。对事件字段的改动尤其需要谨慎：一旦历史事件已经存在，删除或改变字段含义可能令旧数据无法被正确解释。比起追求一次写完完整行业方案，更可持续的方式是让每个变更都可回滚、可验证、可追踪。
一个适合两周试点的验收清单
如果团队准备把 Celerp 纳入技术选型，可以将第一轮控制在一个非关键流程中，并设置明确的退出条件。第一周重点验证安装、数据库初始化、用户与权限、备份恢复和一条完整业务链；第二周再加入一个小型模块或一个只读集成，观察数据一致性、错误处理和维护成本。试点期间不必追求覆盖全部历史数据，更不应为了演示而绕过正常审批和备份要求。
结束时，建议以可回答的问题而不是主观印象做复盘：关键业务事实能否被追溯？恢复演练耗时多久、遗漏了什么？模块是否能在不修改核心的情况下交付？许可边界是否适合预期的再分发或托管模式？团队是否有能力维护 Python、PostgreSQL 和升级流程？若这些问题中有任何一项无法接受，最有价值的产出仍然是及时停止，而不是继续扩大迁移范围。
采用建议：从可回退的试点开始
Celerp 的吸引力不在于承诺替换所有 ERP，而在于提供一种本地优先、Python 可扩展、以不可变业务事件为中心的实现方向。它值得那些希望掌握数据部署位置、需要将业务规则写进代码、并愿意投入领域建模的团队纳入原型评估。
更稳妥的采用路径不是一次性迁移。先确认许可边界，跑通安装、权限和备份恢复；再选择独立或边缘的流程做试点，验证关键单据和账务规则，最后才评估模块扩展和跨系统集成。这样既能看清架构收益，也能在成本变大之前识别真实边界。