SolidInvoice 3.1.2 介绍与选型指南

目标：面向需要自建计费/开票平台的团队与个人，讲清 SolidInvoice 是什么、能做什么、技术架构如何、部署形态有哪些，并与同类开源竞品做量化选型对比。本文为认知篇，全部信息溯源自官方仓库与官方文档（GitHub SolidInvoice/SolidInvoice、solidinvoice.co），溯源与查询日期为 2026-10-24，未包含本地实测内容。

一、环境信息

本文是认知篇（联网溯源），不涉及本地实验环境。信息取证口径如下：

• 软件：SolidInvoice（开源计费与开票系统）
• 官方仓库：https://github.com/SolidInvoice/SolidInvoice
• 官方网站：https://solidinvoice.co（营销站与文档入口）、https://solidinvoice.app（官方托管 SaaS 与在线 API 文档）
• 官方文档站：https://solidinvoice.co/docs（Docusaurus 站点，源码位于仓库 docs/docs/ 目录）
• 最新稳定版：3.1.2（发布于 2026-10-22，来源：GitHub Releases Atom Feed https://github.com/SolidInvoice/SolidInvoice/releases.atom，查询日期 2026-10-24）
• 许可证：MIT（来源：仓库 3.1.2 tag composer.json 的 license 字段）
• 维护方：SolidWorx（作者 Pierre du Plessis，来源：仓库源码文件头版权声明）
• 社区活跃度取证：GitHub Stars 978、Docker Hub 拉取量约 145k（来源：shields.io 徽章 img.shields.io/github/stars/SolidInvoice/SolidInvoice 与 img.shields.io/docker/pulls/solidinvoice/solidinvoice，查询日期 2026-10-24）

二、软件概述

SolidInvoice 是一个面向自由职业者与小企业的开源计费与开票（Invoicing/Billing）平台，官方定位为 "The open-source invoicing platform for freelancers and small businesses"（来源：仓库 README，2026-10-24 查询）。它提供报价单（Quote）、发票（Invoice）、周期发票（Recurring Invoice）、客户管理、在线收款、多币种与多税率的完整计费链路，既能作为官方托管服务使用（solidinvoice.app，8 美元/月），也能 100% 自托管（MIT 许可，免费）。

💡 技术拓展：计费/开票类软件按收费模型可分为「按账单收款的开票工具」与「按订阅周期计费的计费引擎」两类。前者面向"给客户开发票"场景（SolidInvoice、InvoicePlane、Invoice Ninja），后者面向"按用量/订阅自动扣款"场景（Kill Bill、Lago）。SolidInvoice 覆盖前者全量能力，并通过周期发票（Recurring Invoice）覆盖轻量订阅场景；本文选型对比按此口径展开。

基本信息速览（来源：仓库 README 与 3.1.2 tag composer.json）：

版本节奏（来源：GitHub Releases Atom Feed，查询日期 2026-10-24）：3.0.0-beta1 → 3.0.0 → 3.0.1 → 3.1.0（2026-10-17）→ 3.1.1（2026-10-17）→ 3.1.2（2026-10-22），3.x 线处于活跃迭代期，patch 版本以周为单位发布。

三、核心架构

SolidInvoice 是一个标准的 Symfony 单体应用（Modular Monolith），按业务域拆分为多个 Symfony Bundle，通过 Doctrine ORM 映射数据库，前端为服务端渲染 + Stimulus 增强。以下架构信息溯源自仓库源码目录结构与官方文档（查询日期 2026-10-24）。

3.1 技术分层

3.2 业务 Bundle 划分（源码目录证据）

仓库 src/ 目录按业务域组织（来源：仓库 3.1.2 tag 文件树，经 jsDelivr 镜像站取数，查询日期 2026-10-24）：CoreBundle（核心配置与遥测）、InvoiceBundle（发票/周期发票）、QuoteBundle（报价）、ClientBundle（客户与联系人）、PaymentBundle（支付与 Payum 集成）、TaxBundle（税率）、UserBundle（用户与 API Token）、ApiBundle（API 鉴权）、McpBundle（AI Agent 的 MCP 服务）、InstallBundle（安装向导）、NotificationBundle（通知）、CronBundle（定时任务）、SaasBundle（托管版相关）等。

3.3 关键运行机制

• 发票状态机：发票走 draft → pending → paid 状态流转（README 原文 "Invoice state machine (draft → pending → paid)"），由 Symfony Workflow 组件驱动，逾期自动标记与付款提醒由后台任务完成。
• 后台任务内建：容器化发行、二进制、Homebrew 发行形态中，周期发票生成与异步邮件投递的 worker 随主进程自动运行，无需另配 cron（来源：官方文档 docs/docs/installation-guide/docker.md "Recurring tasks and async work (email sending) run automatically inside the container"）；仅 Git/发行包安装需要按 cron-job-setup.md 另行配置。
• 多公司与多租户：单实例可运行多个公司（multi-tenancy out of the box），Doctrine 层做公司数据过滤，API Token 与公司绑定（来源：README 与官方 REST API 文档）。
• 配置目录：应用生成的密钥、安装状态、SQLite 数据库（未接外部库时）统一落在配置目录（容器化发行形态为 /etc/solidinvoice，二进制形态为 ~/.SolidInvoice/），来源：官方构建文件 docker/package.Dockerfile 的 SOLIDINVOICE_CONFIG_DIR 环境变量与 docs/docs/installation-guide/quick-install.mdx。

四、功能特性

以下特性清单溯源自仓库 README（2026-10-24 查询）：

4.1 计费与开票

• 报价单一键转换为发票；周期发票按灵活计划自动生成。
• 多币种支持：金额使用真实 Money 对象表达，规避浮点舍入误差。
• 多税支持：行级税、发票级税调整，开票时对税率做快照。
• 比例税与固定税两种税型，行级折扣。
• 8 套内置 PDF 发票/报价模板。
• 逾期发票自动检测，可配置逾期通知与按计划的付款提醒。
• 发票状态机：draft → pending → paid。

4.2 客户与联系人

• 客户与联系人全量管理，支持自定义字段（客户、联系人、发票、报价均可扩展字段）。
• 按客户设置币种、地址与联系渠道。

4.3 用户与安全

• TOTP 两步验证（2FA）、Google OAuth 登录、用户邮箱验证。
• 基于 Symfony Security 与 Voters 的角色访问控制（RBAC）。
• 新用户引导清单（onboarding checklist）。

4.4 支付收款

• 通过 Payum 接入自带账号的 Stripe、PayPal 等网关。
• 发票附带在线支付链接；卡数据不经自托管服务器，天然规避 PCI 合规负担。

4.5 集成与 API

• REST API（JSON-LD、JSON-HAL、JSON、XML），由 API Platform 4 驱动，X-API-TOKEN 令牌鉴权，实例自带 /api/docs Swagger UI。
• 内置 MCP Server（OAuth2 授权），支持 AI Agent 自动化操作业务数据。
• Meilisearch 全文检索集成；网格导出与全公司数据导出（CSV/JSON/XML）。
• 通知通道覆盖邮件、短信与聊天渠道（Symfony Notifier 生态，仓库 composer.json 中含 Telegram/Slack/Twilio/Amazon SNS 等数十个 Notifier 桥接）。

4.6 隐私与工程化

• 100% 可自托管：数据库归自己管，MIT 许可允许 fork 与二次分发。
• 密钥加密存储、ULID 主键、PHPStan level 6 静态分析、PHPUnit 测试与 GitHub Actions CI（来源：README "Modern Stack" 小节）。
• Kubernetes Helm charts 与可选 Prometheus 指标端点。

五、快速开始（最小可用示例）

以下命令均引自官方文档（未做本地实测），用于建立对启动成本的直观认知。

方式一：官方容器化发行（来源：官方文档 docs/docs/installation-guide/docker.md）：官方在 Docker Hub 发布多架构发行物 solidinvoice/solidinvoice，单条启动命令即可拉起应用（监听 8765 端口，配置目录 /etc/solidinvoice 挂载持久卷），首次访问进入安装向导完成数据库与管理员配置。完整编排与落地过程见本专栏《SolidInvoice 3.1.2 Docker Compose 部署指南》。

方式二：自包含二进制（来源：官方文档 docs/docs/installation-guide/quick-install.mdx）：

# 一键安装脚本，装到 /usr/local/bin（默认装最新稳定版，可用 VERSION=3.1.2 指定）
curl -fsSL https://raw.githubusercontent.com/SolidInvoice/SolidInvoice/3.0.x/packaging/install.sh | sh
solidinvoice run

二进制内嵌 PHP 运行时与 Caddy Web 服务器，无需单独安装 PHP/Composer/Nginx；默认监听 https://localhost:8765（自签证书），SQLite 数据库开箱即用，装完即进入安装向导。

健康检查（来源：官方文档 quick-install.mdx）：

curl http://localhost:8765/health
# 应用正常运行时返回 OK（HTTP 200）

API 侧最小示例（来源：官方文档 docs/docs/api/rest-api.md；令牌在 Web 界面 Settings → API Keys 创建）：

curl -H "X-API-TOKEN: <your-token>" \
     -H "Accept: application/ld+json" \
     https://your-instance.example/api/invoices

⚠️ 说明：正式部署（含 MySQL + 数据持久化 + 定制环境变量）建议直接使用 Docker Compose 编排，官方仓库根目录提供了 docker-compose.yml（app + mysql:8.0 两服务）示例；完整落地过程见本专栏《SolidInvoice 3.1.2 Docker Compose 部署指南》。

六、适用场景与限制

6.1 适合的场景

• 自由职业者/小企业自建开票：报价、开票、收款、提醒全链路闭环，零许可成本。
• 对数据主权有要求的团队：MIT 许可 + 全量自托管，发票与客户数据不出自有服务器。
• 需要 API 集成的业务流：REST API + GraphQL + MCP Server 三种集成面，适合接入 ERP、报表或 AI Agent 自动化。
• 多主体记账：单实例多公司，代理记账/多品牌经营场景友好。

6.2 已知限制（官方口径）

• 无原生 Windows 版：自包含二进制仅支持 64 位 Linux（x86_64/arm64）与 macOS（Intel/Apple Silicon），Windows 需走 WSL2（来源：quick-install.mdx）。
• 数据库依赖：SQLite 适合小规模与试用，生产并发场景官方推荐接 MySQL/MariaDB/PostgreSQL（来源：安装向导文档 system-installation.md）。
• 托管版差异：托管版（8 美元/月）移除 SolidInvoice 品牌、自动更新与备份、新特性先享；自托管版这些均需自理（来源：README Self-Hosted vs Hosted 对比表）。
• 3.x 为活跃开发线：3.1.x 以周为单位发版，升级需关注仓库 UPGRADE.md。

七、同类选型对比

对比数据取证口径：竞品定位与许可来自各竞品官方站点/仓库公开信息与 SolidInvoice 官方对比页（solidinvoice.co 下 vs-invoice-ninja、vs-freshbooks、vs-quickbooks、vs-wave、vs-zoho-invoice 等页面，2026-10-24 查询）；SolidInvoice 数据同本文第二、七节来源。Star 数为 shields.io 徽章读数（SolidInvoice 978，查询日期 2026-10-24；竞品未逐一取证，以「同类平台已有专栏」标注供横向定位）。

7.1 与同类自托管开票平台对比

选型解读：要"从 0 到 1 快速自建开票系统且保留 API 自动化能力"，SolidInvoice 与 Invoice Ninja 同档；SolidInvoice 的差异化在 MIT 许可（商用无白标限制）、内嵌运行时带来的极低部署成本（单二进制/单容器发行物）、以及 MCP/GraphQL 等新形态集成面。若只需要"手工开票"且极简，InvoicePlane 足够；若核心诉求是用量计费/订阅扣款引擎，应选 Kill Bill 或 Lago 而非开票工具。

7.2 社区活跃度与版本节奏量化

💡 说明：978 Star 属中小体量项目，但版本以周为单位持续发布、官方文档站完整度高、且有商业托管服务兜底（商业收入反哺开源维护），工程活跃度高于同 Star 体量的一般项目。对"开票"这类长周期使用的业务系统，维护活跃度比 Star 数更重要。

7.3 兼容矩阵

八、参考链接

• 官方仓库：https://github.com/SolidInvoice/SolidInvoice
• 官方网站：https://solidinvoice.co
• 官方文档站：https://solidinvoice.co/docs
• 官方 REST API 文档：https://solidinvoice.co/docs/api/rest-api（实例内 Swagger UI：https://<your-instance>/api/docs）
• Docker Hub 镜像：https://hub.docker.com/r/solidinvoice/solidinvoice
• 版本发布列表：https://github.com/SolidInvoice/SolidInvoice/releases
• 本专栏部署落地：《SolidInvoice 3.1.2 Docker Compose 部署指南》