XYCRM:把一整套 CRM 装进一台家用 NAS

一台飞牛 NAS + 一个 HTML 文件 + 一个纯标准库的 Python 脚本,跑出了客户、合同、回款、提醒、拜访的完整闭环。数据在自己机房里,多账号各管各的客户池。


一、它解决什么问题

大多数小团队用 CRM 会卡在同一个岔路口:

方案卡在哪
SaaS CRM客户数据存在别人服务器上、按人头收年费、功能 90% 用不上,光配置就要学一周
Excel / 在线表格多人同时改容易乱、没有权限、没有提醒、合同附件到处飞、历史版本找不回
自己写一套要买服务器、配数据库、搞运维,一个前端框架没选好就烂尾

XYCRM 走的是第四条路:数据存在自己的 NAS 上,形态是一套「单文件网页 + 零依赖后端」的应用,装完即用,局域网任何设备打开浏览器就是同一份数据。

它的取舍很明确——不做集群、不做微服务、不引入任何第三方依赖,把复杂度全部压在「一个 HTML 文件」和「一个 Python 文件」里,换来的是:

  • 部署 = 装一个应用包(或双击一个 dmg),没有 npm install,没有数据库迁移
  • 备份 = 复制一个 JSON 文件
  • 升级 = 覆盖安装,数据自动保留
  • 私有 = 数据不出自己家门

二、功能全景

系统共 9 个页面,覆盖一条完整的小团队业务流:找客户 → 记拜访 → 签合同 → 收回款 → 跟提醒。

首页(原「总看板」)

  • 一排可点击的统计卡:客户总数、热点客户、待办提醒、合同总数、金额合计、累计回款、待收金额、逾期提醒——点哪张卡跳哪个页面
  • 整月日历:把提醒(蓝)、合同到期(琥珀)、回款(绿,chip 直接显示金额)、备忘(紫)、拜访(青)五类日程落在对应日期上;格角有当日事项数角标,格内最多 3 条、多余收成「+N 项」
  • 法定节假日:内置国务院办公厅的放假安排,放假格淡红底 +「休」角标、调休上班灰底 +「班」角标,日历下方还有当月假期一览,点一下直接跳到那天
  • 选中某天展开当天明细,点事项直接打开对应的编辑弹窗
  • 日历「备忘」:挂在某一天的自由记事,紫色 chip,点开就编辑

客户管理

  • 客户档案(公司、联系人、电话、地址、标签、备注、归属)
  • 列宽可拖动:表头拖手柄调列宽,双击手柄恢复该列、工具栏按钮恢复全部,列宽存在本机浏览器
  • 分页 + 搜索 + 排序:10 / 20 / 50 / 100 / 全部显示,支持按添加日期、最近更新、公司名(拼音)排序
  • 批量操作:行复选框 + 表头全选(带半选态),批量标热点 / 关注 / 删除;已勾选跨页保留
  • 客户详情弹窗内按需显示合同、回款、提醒、拜访区块

客户管理(浅色主题).png

热点关注

  • ★ 热点客户 / ♥ 关注客户两档名单,两档互斥(标热点自动退出关注,反之亦然)
  • 页面拆成上下两个同构面板,各自带分页条、各自勾选、批量条统计两表选中总和

拜访记录

  • 按天分组的竖向时间线,每天一组:日期 / 星期 /「今天·昨天·N 天前」/ 当天次数,未来的自动打「计划」标签
  • 顶部统计卡含「本月出差天数」「今年出差天数」(同一天跑几家只算 1 天)
  • 三个筛选(时间范围 / 客户 / 排序)+ 关键词搜索,支持记不挂客户的拜访(展会、跑市场)

提醒事项

  • 关联客户 + 提醒时间 + 备注 + 完成状态
  • 备注与客户档案打通:关联客户的提醒,备注就是客户档案备注的同一份数据,双向同步;自己手写的内容不会被覆盖
  • 分页 + 状态筛选 + 搜索(提醒内容 / 备注 / 客户名)

合同管理

  • 合同名称、编号、客户、金额、回款进度、签订日期、有效期、状态、备注、附件
  • 状态选「已完成 / 已终止」时到期日自动禁用,且不再进入首页到期提醒与日历
  • 合同附件(📎 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-051.0.0 → 1.6.010
10-061.6.1 → 1.7.911
10-071.8.0 → 1.9.312
10-081.9.4 → 1.9.1411
10-091.9.15 → 1.9.239
合计1.0.0 → 1.9.2353

最近的几条主线:

  • 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 界面(深色 / 浅色主题)。

暂无评论

发送评论 编辑评论


				
|´・ω・)ノ
ヾ(≧∇≦*)ゝ
(☆ω☆)
(╯‵□′)╯︵┴─┴
 ̄﹃ ̄
(/ω\)
∠( ᐛ 」∠)_
(๑•̀ㅁ•́ฅ)
→_→
୧(๑•̀⌄•́๑)૭
٩(ˊᗜˋ*)و
(ノ°ο°)ノ
(´இ皿இ`)
⌇●﹏●⌇
(ฅ´ω`ฅ)
(╯°A°)╯︵○○○
φ( ̄∇ ̄o)
ヾ(´・ ・`。)ノ"
( ง ᵒ̌皿ᵒ̌)ง⁼³₌₃
(ó﹏ò。)
Σ(っ °Д °;)っ
( ,,´・ω・)ノ"(´っω・`。)
╮(╯▽╰)╭
o(*////▽////*)q
>﹏<
( ๑´•ω•) "(ㆆᴗㆆ)
😂
😀
😅
😊
🙂
🙃
😌
😍
😘
😜
😝
😏
😒
🙄
😳
😡
😔
😫
😱
😭
💩
👻
🙌
🖕
👍
👫
👬
👭
🌚
🌝
🙈
💊
😶
🙏
🍦
🍉
😣
Source: github.com/k4yt3x/flowerhd
颜文字
Emoji
小恐龙
花!
上一篇
下一篇