最完整Spliit指南：从部署到智能记账全流程
项目地址: https://gitcode.com/gh_mirrors/sp/spliit 引言：终结AA制烦恼的开源解决方案
你还在为朋友聚会AA制算账浪费30分钟？团队出差费用分摊Excel公式错漏百出？Spliit作为Splitwise最佳开源替代方案，让费用管理像聊天一样简单。本文将带你从0到1掌握这款工具的本地部署、核心功能与高级技巧，读完你将获得：
- 3种部署方式的详细操作手册（开发环境/容器/生产环境）
- 10个核心功能的 step-by-step 使用指南
- 5个高级配置技巧（含S3存储/收据扫描）
- 完整问题排查清单与性能优化建议
项目全景：为什么Spliit值得选择
开源费用分摊工具对比表
| 特性 | Spliit (开源) | Splitwise (商业) | 传统Excel |
|---|---|---|---|
| 永久免费使用 | ✅ | ❌ 高级功能付费 | ✅ |
| 数据隐私自主掌控 | ✅ 本地部署 | ❌ 云端存储 | ✅ |
| 多人实时同步 | ✅ | ✅ | ❌ |
| 费用类别分析 | ✅ | ✅ | ❌ |
| 收据扫描录入 | ✅ (需配置) | ✅ 高级版 | ❌ |
| 自定义货币支持 | ✅ 全球货币 | ✅ | ✅ 手动 |
| 开源可扩展 | ✅ 完全开源 | ❌ 闭源 | ❌ |
核心功能架构图
环境部署：3种方案任你选
方案1：本地开发环境（适合开发者）
部署步骤
# 1. 克隆仓库（替换为国内地址）
git clone https://gitcode.com/gh_mirrors/sp/spliit
cd spliit
# 2. 启动本地PostgreSQL数据库
./scripts/start-local-db.sh
# 3. 配置环境变量
cp .env.example .env
# 编辑.env文件设置必要参数
# DATABASE_URL="postgresql://postgres:postgres@localhost:5432/spliit"
# 4. 安装依赖并初始化数据库
npm install
# 自动执行数据库迁移
# 5. 启动开发服务器
npm run dev
# 访问 http://localhost:3000
依赖检查清单
| 依赖项 | 版本要求 | 检查命令 |
|---|---|---|
| Node.js | ≥18.0.0 | node -v |
| npm | ≥9.0.0 | npm -v |
| PostgreSQL | ≥14.0 | psql --version |
| Docker (可选) | ≥20.10 | docker --version |
方案2：Docker容器部署（适合团队共享）
容器化部署流程
# 1. 构建Docker镜像
npm run build-image
# 2. 配置容器环境变量
cp container.env.example container.env
# 编辑数据库连接等参数
# 3. 启动服务栈
npm run start-container
# 4. 验证服务状态
curl http://localhost:3000/api/health
# 预期响应: {"status":"ok","database":"connected"}
容器架构图
核心功能使用指南
快速上手流程图
1. 群组管理
创建高效群组的5个最佳实践
- 命名规范：使用"2024-家庭共用"格式包含时间维度
- 货币选择：创建时确认货币，后续无法更改
- 成员管理：及时移除不再参与的成员避免权限问题
- 描述信息：添加群组用途说明，如"每月聚餐AA制"
- 定期归档：完成使命的群组标记为"已归档"
创建群组代码示例（API调用）
// 前端调用示例
const createGroup = async () => {
const result = await trpc.groups.create.mutate({
name: "2024-家庭共用",
description: "日常家庭开支分摊",
currencyCode: "CNY",
isFavorite: true
});
// 分享群组链接
copyToClipboard(`http://localhost:3000/groups/${result.id}`);
};
2. 费用管理全流程
费用创建表单关键字段说明
| 字段 | 填写建议 | 注意事项 |
|---|---|---|
| 金额 | 保留两位小数 | 支持负数表示退款 |
| 日期 | 选择实际消费日期而非录入日期 | 影响统计报表的时间维度 |
| 参与人 | 精确选择实际参与者 | 未参与人不会计入分摊 |
| 分摊方式 | 平等/比例/自定义金额 | 总额需等于费用金额 |
| 类别 | 选择最具体的分类 | 影响后续统计分析 |
| 描述 | 包含商家和物品信息 | 便于搜索和回忆 |
高级费用分摊示例
高级配置与优化
S3文档存储配置（支持收据上传）
- 创建S3兼容存储（如阿里云OSS/腾讯云COS）
- 配置环境变量：
# .env文件添加
NEXT_PUBLIC_ENABLE_EXPENSE_DOCUMENTS=true
S3_UPLOAD_KEY=你的访问密钥
S3_UPLOAD_SECRET=你的安全密钥
S3_UPLOAD_BUCKET=存储桶名称
S3_UPLOAD_REGION=区域代码（如oss-cn-beijing）
S3_UPLOAD_ENDPOINT=https://oss-cn-beijing.aliyuncs.com
- 验证配置：创建费用时出现"上传收据"按钮即表示成功
收据扫描功能启用（AI识别）
- 获取OpenAI API密钥（需国内可访问的API服务）
- 配置环境变量：
NEXT_PUBLIC_ENABLE_RECEIPT_EXTRACT=true
OPENAI_API_KEY=你的API密钥
# 可选配置
OPENAI_API_BASE_URL=国内代理地址
- 使用方法：创建费用时选择"扫描收据"，上传清晰图片自动提取金额、日期和商家信息
问题排查与性能优化
常见错误解决方案
| 错误现象 | 可能原因 | 解决方案 |
|---|---|---|
| 数据库连接失败 | PostgreSQL未启动 | 执行./scripts/start-local-db.sh重启 |
| 依赖安装报错 | Node版本过低 | 升级Node.js至v18+ |
| 开发服务器启动失败 | 端口被占用 | 修改package.json中的dev命令添加--port 3001 |
| 功能按钮不显示 | 环境变量未配置 | 检查.env文件对应功能的开关变量 |
性能优化建议
- 数据库索引优化：
-- 为常用查询字段添加索引
CREATE INDEX idx_expenses_group_id ON expenses(groupId);
CREATE INDEX idx_expenses_date ON expenses(date);
- 前端加载优化：
// 组件懒加载示例
const ExpenseChart = dynamic(() => import('@/components/expense-chart'), {
loading: () => <Skeleton height={300} />,
ssr: false
});
总结与未来展望
Spliit作为开源费用分摊解决方案，不仅提供了Splitwise的核心功能，更通过可本地部署、数据自主掌控和高度可扩展性满足了隐私敏感用户的需求。通过本文介绍的部署方法，你可以在10分钟内搭建起自己的费用管理系统，无论是家庭日常、朋友聚会还是小型团队，都能找到适合的使用场景。
功能 roadmap 预测
- 数据导入导出功能（Q1 2025）
- 多语言界面优化（进行中）
- 离线操作支持（规划中）
- 预算管理功能（需求收集）
你可能还想了解
- [进阶] 数据库备份与迁移策略
- [技巧] 使用标签功能实现多级分类
- [开发] 贡献代码指南与流程
收藏本文，下次遇到费用分摊难题随时查阅！如有疑问或建议，欢迎在项目仓库提交issue。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
