一台飞牛 NAS + 一个 HTML 文件 + 一个纯标准库的 Python 脚本,跑出了客户、合同、回款、提醒、拜访的完整闭环。数据在自己机房里,多账号各管各的客户池。
一、它解决什么问题
大多数小团队用 CRM 会卡在同一个岔路口:
| 方案 | 卡在哪 |
|---|---|
| SaaS CRM | 客户数据存在别人服务器上、按人头收年费、功能 90% 用不上,光配置就要学一周 |
| Excel / 在线表格 | 多人同时改容易乱、没有权限、没有提醒、合同附件到处飞、历史版本找不回 |
| 自己写一套 | 要买服务器、配数据库、搞运维,一个前端框架没选好就烂尾 |
XYCRM 走的是第四条路:数据存在自己的 NAS 上,形态是一套「单文件网页 + 零依赖后端」的应用,装完即用,局域网任何设备打开浏览器就是同一份数据。
它的取舍很明确——不做集群、不做微服务、不引入任何第三方依赖,把复杂度全部压在「一个 HTML 文件」和「一个 Python 文件」里,换来的是:
- 部署 = 装一个应用包(或双击一个 dmg),没有 npm install,没有数据库迁移
- 备份 = 复制一个 JSON 文件
- 升级 = 覆盖安装,数据自动保留
- 私有 = 数据不出自己家门
-1024x643.png)
二、功能全景
系统共 9 个页面,覆盖一条完整的小团队业务流:找客户 → 记拜访 → 签合同 → 收回款 → 跟提醒。
首页(原「总看板」)
- 一排可点击的统计卡:客户总数、热点客户、待办提醒、合同总数、金额合计、累计回款、待收金额、逾期提醒——点哪张卡跳哪个页面
- 整月日历:把提醒(蓝)、合同到期(琥珀)、回款(绿,chip 直接显示金额)、备忘(紫)、拜访(青)五类日程落在对应日期上;格角有当日事项数角标,格内最多 3 条、多余收成「+N 项」
- 法定节假日:内置国务院办公厅的放假安排,放假格淡红底 +「休」角标、调休上班灰底 +「班」角标,日历下方还有当月假期一览,点一下直接跳到那天
- 选中某天展开当天明细,点事项直接打开对应的编辑弹窗
- 日历「备忘」:挂在某一天的自由记事,紫色 chip,点开就编辑
客户管理
- 客户档案(公司、联系人、电话、地址、标签、备注、归属)
- 列宽可拖动:表头拖手柄调列宽,双击手柄恢复该列、工具栏按钮恢复全部,列宽存在本机浏览器
- 分页 + 搜索 + 排序:10 / 20 / 50 / 100 / 全部显示,支持按添加日期、最近更新、公司名(拼音)排序
- 批量操作:行复选框 + 表头全选(带半选态),批量标热点 / 关注 / 删除;已勾选跨页保留
- 客户详情弹窗内按需显示合同、回款、提醒、拜访区块

热点关注
- ★ 热点客户 / ♥ 关注客户两档名单,两档互斥(标热点自动退出关注,反之亦然)
- 页面拆成上下两个同构面板,各自带分页条、各自勾选、批量条统计两表选中总和
拜访记录
- 按天分组的竖向时间线,每天一组:日期 / 星期 /「今天·昨天·N 天前」/ 当天次数,未来的自动打「计划」标签
- 顶部统计卡含「本月出差天数」「今年出差天数」(同一天跑几家只算 1 天)
- 三个筛选(时间范围 / 客户 / 排序)+ 关键词搜索,支持记不挂客户的拜访(展会、跑市场)
-1024x643.png)
提醒事项
- 关联客户 + 提醒时间 + 备注 + 完成状态
- 备注与客户档案打通:关联客户的提醒,备注就是客户档案备注的同一份数据,双向同步;自己手写的内容不会被覆盖
- 分页 + 状态筛选 + 搜索(提醒内容 / 备注 / 客户名)
合同管理
- 合同名称、编号、客户、金额、回款进度、签订日期、有效期、状态、备注、附件
- 状态选「已完成 / 已终止」时到期日自动禁用,且不再进入首页到期提醒与日历
- 合同附件(📎 N 个附件),走
Authorization头 + blob 下载,URL 上不带 token - 分页 + 状态筛选 + 搜索(合同名 / 编号 / 备注 / 客户名)
回款管理
- 统计卡:合同总金额、累计回款、待收金额、本月回款、未结清合同数
- 应收账款 · 未收齐合同:按未收金额倒序,显示已收 / 未收 / 进度条,已到期未收齐的标红
- 回款流水:按日期倒序,按客户 / 合同 / 流水号搜索
- 登记回款时客户与合同双向联动,自动把该合同的未收金额预填进金额框;没选合同时自动挂「未收最多」的那份,避免「记了回款、应收账款里看不到」

企业查询
- 新增 / 编辑客户时点「🔍 查企业」:输入简称 → 候选列表 → 点一条自动补全企业全称、地址、电话
- 两个通道二选一:
| 通道 | 能拿到 | 需要 |
|---|---|---|
| 百度地图(默认) | 企业全称、地址、电话 | 一个免费 AK |
| 风鸟 RiskBird | 上述 + 法人、信用代码、注册资本、成立日期、经营范围 | 风鸟 API Key |
| 兜底(都不配) | 只用百度搜索联想补出企业全称 | 无 |
- AK / Key 只存 NAS 本机,接口走服务端代理,浏览器拿不到明文
数据备份
- 导出 JSON / CSV(客户、合同、回款都带统计列)
- WebDAV 云端自动备份:数据 + 附件打成一个 zip,按间隔(默认 24 小时)自动上传,失败 10 分钟后重试;支持保留份数、从云端任选一份恢复
设置
- 用户管理(仅管理员)、安全(二次验证 / 活跃会话 / 登录与安全日志)、推送(WxPusher 微信提醒)、外观(跟随系统 / 白天 / 夜晚)、企业查询

三、多账号与客户池:既共享又隔离
这是 v1.9.22 的大改,也是从「一个密码全班共用」到「一套真账号体系」的分水岭。
两级角色
- 管理员:首次打开时创建(用户名 + 两次密码),可开关二次验证、管理用户、看安全日志、管推送与备份
- 成员:由管理员在「设置 → 用户管理」里新建 / 删除 / 重置密码,登录只需用户名 + 密码,不走二次验证
客户池 vs 个人客户
每个客户带一个「归属」字段,决定谁能看见:
| 归属 | 谁能看见 |
|---|---|
| 留空 = 客户池 | 全员可见 |
| 指定成员 = 该同事的个人客户 | 仅归属人 + 管理员可见 |
合同 / 提醒 / 回款 / 拜访跟随所属客户的归属;没挂客户的记录归创建者本人。客户列表行和客户档案里都有归属角标(「客户池」「我的个人客户」「某某的个人客户」)。
服务端是怎么防越权的
前端隐藏入口只是表面功夫,真正的边界在后端:
GET /api/data按登录身份裁剪:成员只拿到「客户池 + 自己的」记录PUT /api/data是合并保存:只合并自己看得见的那部分改动,别人的记录原样保留;已存在但自己看不见的 id 直接拒绝覆盖;还能防止成员把池子客户「据为己有」(编辑既有记录时若不带归属字段就沿用原值,防洗白)- 敏感接口走前缀白名单:
/api/users、/api/push、/api/backup、/api/security、/api/auth/*(会话 / 改密码 / TOTP)仅管理员可达,成员调用一律 403 - 删用户会立即踢掉该用户所有在线会话,原密码随即失效
顺带在这一版修掉一个藏得很深的后端 bug:部分不读请求体的接口(退出登录、踢会话)在 keep-alive 连接上会残留 body 字节污染下一个请求,偶发 501 Unsupported method '{}POST'——表现就是「退出登录后再登录就报错」。现在请求收尾统一把未读 body 读干净,彻底解决。
四、技术实现
前端:一个单文件
crm.html 约 280KB,HTML / CSS / JS 全部内联,图标以 base64 内联进 <head>(file:// 双击打开也能显示)。没有构建步骤,没有框架,改完刷新即生效。
设计上走 API 优先、localStorage 回退:连不上后端时自动降级为本地存储,纯本地也能用。
视觉是「液态玻璃」(Liquid Glass)设计系统:backdrop-filter 磨砂、两级圆角、物理缓动曲线、明确的 z-index 层级;Safari 走 -webkit- 前缀,不支持的老浏览器回退不透明底色,窄屏自动降 blur 省电,prefers-reduced-motion 下关掉全部动画。
后端:纯标准库
server.py 只用 Python 标准库(ThreadingHTTPServer),零第三方依赖——不需要 pip install,NAS 自带 python3 就能跑。手写了 TOTP(过 RFC 6238 官方测试向量)、限速、会话管理、静态资源扩展名白名单。
存储:一个 JSON
- 数据文件:
crm-data.json(在 NAS 的/vol{n}/@appdata/simplecrm/) - 每次保存前自动在
backup/留上一版,最多 10 份 - 合同附件放同目录
files/ - 卸载应用不会删数据,重新安装自动读取
安全
- 登录失败指数退避:同 IP 连错 5 次锁 60 秒,之后每次翻倍,封顶 1 小时
- 会话 30 天有效 + 连续 14 天无请求自动失效;设置页可看所有在线设备并逐个踢下线
- 二次验证(TOTP)+ 8 个一次性恢复码,二维码本机生成、密钥不发往任何第三方
- 登录成功 / 失败、限速、改密码、踢设备、开关二次验证全部落盘安全日志(保留 500 条)
五、两种形态
飞牛 fnOS(NAS 版)
应用中心 → 手动安装 → 选 dist/simplecrm-x.y.z.fpk → 装完桌面出现 XYCRM 图标
其它设备访问:http://NAS的IP:8790
- 固定端口 8790,被占用时安装直接报错
- 官方
fnpack打包(应用代码打成app.tgz并写入 checksum),结构不对安装会报「app.tgz 失败」 run-daemon.sh守护,进程挂了 5 秒内自动拉起- 升级用新包覆盖安装,
cmd/main start会先比对/api/health版本号,不一致就杀掉旧进程重启(避免「文件换了、内存还是旧代码」的鬼故事)
macOS(dmg)
- 原生窗口外壳:Swift + 系统自带 Cocoa / WebKit,整个 app 不到 700KB,不捆绑 Python,双击出独立窗口而不是甩给浏览器
- 附件下载 / 预览通过 JS 桥落到
~/Downloads;接管了alert/confirm/prompt改原生弹窗;关窗即停本机服务,不留孤儿进程 - 登录页可填 NAS 地址一键切到远端数据,本地和 NAS 两种用法同一个包
外网访问
NAS 侧零改代码,用 Cloudflare Tunnel 暴露 8790,再叠一层 Cloudflare Access 邮箱白名单——登录口在边缘就不可达。应用自身的加固(静态扩展名白名单、按真实 IP 分桶限速、全局兜底闸门、未登录不暴露版本号)在 v1.9.3 一并做齐。
六、五天,53 个版本
这个项目从零到 v1.9.23 只用了 5 天,迭代节奏是「先跑通基础版本,再一版一个特性往上叠」:
| 日期 | 版本区间 | 版数 |
|---|---|---|
| 10-05 | 1.0.0 → 1.6.0 | 10 |
| 10-06 | 1.6.1 → 1.7.9 | 11 |
| 10-07 | 1.8.0 → 1.9.3 | 12 |
| 10-08 | 1.9.4 → 1.9.14 | 11 |
| 10-09 | 1.9.15 → 1.9.23 | 9 |
| 合计 | 1.0.0 → 1.9.23 | 53 |
最近的几条主线:
- 1.9.23 提醒事项 / 合同管理加分页与每页条数,四张列表共用同一档位
- 1.9.22 多账号 + 客户池 / 个人客户,合同与提醒加搜索框,顺手修掉 keep-alive body 污染 bug
- 1.9.17 总看板改名「首页」
- 1.9.12 客户列表分页,1.9.10 起 macOS 版换成原生窗口
- 1.9.7 Liquid Glass 视觉改版
- 1.9.0 登录安全加固 + 二次验证
- 1.8.0 拜访记录,1.7.0 回款管理,1.6.0 企业查询双通道
配套的回归测试累计 265 项:接口 91 + 多用户 / 归属隔离 52 + 百度通道 52 + 风鸟通道 38 + WebDAV 32,全部自带 mock 桩、不打真实外部接口。
有两个版本号的小插曲值得记:1.2.1 / 1.2.2 直接跳过了;「1.7.10」从没发布过——因为版本号做字符串比较时
1.7.10会被判成比1.7.9更低(降级),所以从 1.7.9 直接跳到 1.8.0。这类坑现在写进了项目约定。
七、快速上手
# 1) NAS 版:应用中心手动安装
# dist/simplecrm-1.9.23.fpk → 装完访问 http://NAS的IP:8790
# 2) 首次打开设置管理员账号(用户名 + 两次密码)
# 然后到「设置 → 用户管理」把同事加进来,给客户分配归属
# 3) macOS 版:双击 dmg 安装,登录页可填 NAS 地址连远端
# 本机开发调试(不装包也能跑)
python3 simplecrm/app/server.py --port 18790 --web-root simplecrm/app --data-dir /tmp/crmdata
八、一句话总结
XYCRM 是一个私有、零依赖、单文件前端 + 纯标准库后端的轻量 CRM:用一台家用 NAS 换掉了 SaaS 年费和 Excel 协作的混乱,用多账号 + 客户池归属解决了「共享数据」和「保护自己的客户」这个矛盾,用 53 个版本和 265 项回归测试保证了它在自己的机房里稳稳跑着。
配图取自 v1.9.x 界面(深色 / 浅色主题)。