基于Remix与本地存储的订阅管理工具Subs：从设计到部署全解析

1. 项目概述：一个纯粹、高效的订阅费用追踪器

在数字订阅服务泛滥的今天，我们每个人的钱包都在被各种“自动续费”悄悄掏空。从流媒体、云服务到各种软件会员，账单分散在各个平台，支付周期也各不相同，想要清晰地知道自己每个月、每年到底为这些服务花了多少钱，往往需要手动整理一堆邮件和账单，既繁琐又容易遗漏。这正是我决定动手搭建Subs这个开源订阅追踪器的初衷。

Subs 是一个为追求简洁和隐私的用户设计的订阅管理工具。它的核心目标非常明确：让你在一个地方，快速、直观地掌握自己所有的周期性支出，并且完全掌控自己的数据。它不像那些需要你注册账号、将财务数据上传到第三方云端的服务，Subs 的设计哲学是“数据主权归你”。你可以选择将数据完全保存在自己的浏览器本地，或者部署在自己的服务器上，用一个简单的 JSON 文件来存储。整个项目基于现代 Web 技术栈（Remix + React + Tailwind CSS）构建，界面清爽，响应迅速，无论是桌面端还是手机端，操作体验都相当流畅。

如果你是一名开发者，厌倦了臃肿的商业软件，想拥有一个完全受自己控制的订阅管理工具；或者你是一名普通用户，对个人数据隐私有要求，希望找一个轻量、开源、能自部署的方案，那么 Subs 值得你花时间了解一下。接下来，我将从设计思路、技术实现、部署实践到使用技巧，为你完整拆解这个项目。

2. 核心设计思路与技术选型解析

2.1 为什么是“纯前端优先”与“数据本地化”？

在构思 Subs 时，我首先问自己：用户最核心的痛点是什么？答案是：对个人财务数据的隐私担忧和对工具简洁性的追求。很多在线记账或订阅管理工具，功能强大但过于复杂，且数据存储在服务商那里，总让人有些不放心。

因此，Subs 的架构设计围绕两个核心原则展开：

1. 隐私与数据主权：用户的数据应该尽可能留在用户可控的范围内。这催生了 Subs 独特的双存储模式。默认情况下，项目使用一个服务端 JSON 文件（data/config.json）来存储数据。这意味着当你自行部署后，所有数据都保存在你自己的服务器硬盘上，没有中间商。对于更极致的隐私需求，只需一个环境变量USE_LOCAL_STORAGE=true，即可切换到浏览器本地存储（LocalStorage），数据完全不出你的设备。
2. 简洁与高效：功能聚焦于订阅管理的核心流程——增删改查、金额汇总、下次付款日提醒。没有复杂的预算分类、投资关联等冗余功能。界面采用shadcn/ui组件库，基于 Tailwind CSS，确保了视觉的一致性和开发的效率，同时保持了极佳的加载速度。

设计心得：在工具类产品中，克制往往比堆砌功能更难，也更重要。Subs 刻意避免了用户账号系统，因为一旦引入账号，就必然涉及密码、会话、数据库用户表等一系列复杂度。通过“本地存储”和“服务器文件存储”这两种简单模式，我们用一个非常轻量的架构，就解决了数据持久化和隐私的核心诉求。

2.2 技术栈选型的背后考量

Subs 的技术栈看起来是现代 React 生态的一个典型组合，但每个选择都有其具体原因：

• Remix + React：为什么选择 Remix 而不是 Next.js 或纯 React？Remix 的核心优势在于其“服务端为中心”的模型和对 Web 基础标准的拥抱（如<form>提交、action/loader函数）。对于 Subs 这样一个交互以表单为主（添加、编辑订阅）、且需要服务端读写文件（JSON 存储模式）的应用，Remix 的模式非常自然。它简化了数据加载和提交的逻辑，让服务端渲染（SSR）和客户端交互无缝结合。当然，项目提供的关键词包含 Next.js，说明其核心的 React + 现代 CSS 模式同样可以迁移，但 Remix 在当前架构下是更原生的选择。
• Tailwind CSS + shadcn/ui：快速构建美观、一致 UI 的黄金组合。Tailwind 的实用性优先（Utility-First）理念让样式开发速度飞快。shadcn/ui则提供了一套可以直接复制粘贴、高度可定制的 React 组件源码，它不是一个 NPM 包，而是你项目代码的一部分，这避免了版本依赖冲突，也让你能完全控制组件每一个细节。这对于需要精细调整交互的订阅列表、表单对话框非常友好。
• Zustand：状态管理。相比 Redux 的繁琐，Zustand 的 API 极其简洁，一个 Store 文件就能管理所有的订阅状态（列表、增删改查操作、过滤排序状态）。它的轻量性和与 React 的完美融合，使得在客户端管理订阅数据流变得清晰而高效。
• Playwright：端到端（E2E）测试。对于一个管理数据的工具，测试的可靠性至关重要。Playwright 支持多浏览器（Chromium, Firefox, WebKit），能模拟真实用户从打开页面、添加订阅、编辑到删除的完整流程，确保核心功能在任何更新后都不会被意外破坏。
• Biome：一个新兴的、速度极快的 JavaScript 工具链，集成了格式化（Formatting）、代码检查（Linting）等功能，用来替代 ESLint 和 Prettier。选择 Biome 主要是为了追求极致的工具链速度和一体化体验，保持代码风格的统一。

这套技术栈的搭配，在开发体验、性能、可维护性和最终用户体验之间取得了不错的平衡。

3. 功能详解与核心实现逻辑

3.1 订阅数据模型与核心状态管理

一个订阅的核心信息有哪些？Subs 定义了一个清晰的数据结构，这体现在 Zustand Store 和 TypeScript 类型定义中。每个订阅项（Subscription）大致包含以下字段：

interface Subscription { id: string; // 唯一标识，通常使用 `crypto.randomUUID()` 生成 name: string; // 服务名称，如 “Netflix” price: number; // 价格 currency: string; // 货币代码，如 “USD”, “EUR”, “CNY” cycle: 'daily' | 'weekly' | 'monthly' | 'yearly'; // 计费周期 cycleCount: number; // 周期倍数，例如每3个月（cycle: ‘monthly’, cycleCount: 3） startDate: string; // ISO 8601 格式的开始日期，如 “2024-01-15” // ... 可能还有分类、备注等扩展字段 }

所有的订阅项被组织成一个数组，存储在 Zustand 的subscriptionStore中。这个 Store 不仅保存数据，还定义了所有操作数据的方法：addSubscription,editSubscription,deleteSubscription,importFromJson,exportToJson等。

状态流转的关键：当用户在前端界面进行操作（比如点击“保存”按钮）时，会调用 Store 中的对应方法。该方法会先更新内存中的状态（保证UI立即响应），然后根据当前配置的存储模式（USE_LOCAL_STORAGE），调用不同的持久化函数：

• 本地存储模式：直接调用localStorage.setItem。
• 服务端文件存储模式：向一个特定的 Remixaction函数发起fetch请求，由服务端将新数据写入data/config.json文件。

这种设计将业务逻辑（状态管理）与持久化细节（存储层）解耦，使得代码清晰，且未来若要增加新的存储后端（例如连接数据库）也会相对容易。

3.2 智能日期计算与多币种汇总

这是 Subs 的两个核心实用功能。

1. 下次付款日计算：逻辑位于app/utils/nextPaymentDate.ts。计算原理并不复杂，但需要考虑边界情况。核心思路是基于startDate和cycle，计算出下一个大于或等于今天的日期。

• 每月订阅：从开始日期的“日”部分开始，每月递增。需要处理月末特殊情况（如1月31日之后的下次付款，如果当月没有31日，则退回到当月最后一天）。
• 每年订阅：同理，按年递增月份和日期。
• 每周/每日订阅：基于开始日期，按周或日进行周期累加。

实操要点：在实现时，强烈建议使用像date-fns或Day.js这样的日期库来处理日期加减和格式化，避免原生Date对象时区和不直观的 API 带来的坑。Subs 的源码中应该包含了稳健的日期计算逻辑。

2. 多币种汇总：用户可能有美元、欧元、人民币等多种货币的订阅。直接相加是没有意义的。Subs 需要实现货币转换。

• 数据来源：需要一个可靠的汇率 API（如 Open Exchange Rates, Fixer 等，注意：这些是第三方服务，Subs 的演示或开源版本可能需要用户自行配置API密钥或使用免费额度）。
• 实现方式：在服务端（Remixloader）或客户端初始化时，获取一次基础汇率（例如，以 USD 为基准）。前端展示时，将所有非基准货币的订阅价格，通过汇率换算成基准货币后加总，得到总计。同时，也可以在界面上展示各货币的原始小计。
• 缓存策略：汇率不需要实时更新，可以每天或每小时从服务端获取一次并缓存，以减少 API 调用次数和提升页面加载速度。

3.3 响应式UI与键盘快捷键优化体验

Subs 的界面布局充分利用了 Tailwind CSS 的响应式工具类。在桌面端，列表可以更宽，显示更多列信息（如下次付款日、周期）；在移动端，列表会垂直堆叠，或者通过卡片形式展示关键信息，确保触控操作方便。

键盘快捷键是提升效率的利器。Subs 通过useEffect监听全局的keydown事件来实现：

• n：打开新建订阅表单。
• /：将焦点跳到搜索框，这是很多现代Web应用（如Gmail、Notion）的惯例。
• Ctrl/Cmd + e/i：导出/导入 JSON 数据。
• ?：打开快捷键帮助面板。
• Escape：关闭任何打开的弹窗或下拉菜单。

实现时需要注意：当焦点在输入框等表单元素内时，应禁用部分全局快捷键（如/），以免冲突。这可以通过检查event.target的标签名来实现。

4. 从零开始：部署与深度使用指南

4.1 本地开发环境搭建

假设你是一名开发者，想在自己的机器上运行或贡献代码，步骤如下：

1. 环境准备：确保系统已安装 Node.js 20 或更高版本。推荐使用nvm(Node Version Manager) 来管理多版本 Node.js。包管理器可以选择 npm（Node 自带）或速度更快的 Bun。
2. 获取代码：

   git clone https://github.com/ajnart/subs.git cd subs

3. 安装依赖：

   # 使用 npm npm install # 或使用 Bun bun install

4. 启动开发服务器：

   npm run dev # 或 bun run dev

   访问http://localhost:3000，你应该能看到 Subs 的界面。默认情况下，数据会保存在项目根目录的data/config.json文件中（如果该文件不存在，首次添加订阅时会自动创建）。

4.2 生产环境部署方案（Docker 推荐）

对于想长期自托管使用的用户，Docker 是最简单、最一致的方式。

方案一：直接使用 Docker Run这是最快捷的尝鲜方式。以下命令会从 GitHub Container Registry 拉取官方镜像，并将容器内的 7574 端口映射到宿主机的 7574 端口，同时将宿主机的./data目录挂载到容器内，用于持久化存储 JSON 数据文件。

docker run -p 7574:7574 -v $(pwd)/data:/app/data --name subs --rm ghcr.io/ajnart/subs

• -p 7574:7574: 端口映射。
• -v $(pwd)/data:/app/data: 数据卷挂载，这是关键，确保你的订阅数据在容器重启后不会丢失。
• --name subs: 给容器起个名字。
• --rm: 容器停止后自动删除容器（数据在挂载的卷里，所以安全）。
• ghcr.io/ajnart/subs: 官方镜像地址。

方案二：使用 Docker Compose（推荐用于长期运行）创建一份docker-compose.yml文件，内容如下：

version: '3.8' services: subs: image: ghcr.io/ajnart/subs:latest container_name: subs ports: - "7574:7574" # 你可以改成其他端口，如 “8080:7574” restart: unless-stopped # 容器意外退出时自动重启 volumes: - ./data:/app/data # 持久化数据目录 # 环境变量配置（可选） # environment: # - USE_LOCAL_STORAGE=false # 默认即为 false，使用服务端文件存储 # - PORT=7574 # 容器内部端口，一般无需修改

然后，在同一个目录下执行：

# 启动服务（后台运行） docker compose up -d # 查看日志 docker compose logs -f subs # 停止服务 docker compose down

使用 Docker Compose 的优势是配置即代码，易于版本管理和迁移。restart: unless-stopped能保证服务在服务器重启后自动运行。

部署注意事项：

1. 数据备份：定期备份./data目录下的config.json文件。这是你所有订阅数据的命脉。
2. 安全考虑：Subs 本身不包含用户认证。如果你将其部署在公网（例如云服务器），任何人都能访问并修改你的订阅数据。切勿在公网开放不设防的 Subs 服务！解决方案是：
   • 使用反向代理添加认证：在 Subs 前面部署 Nginx 或 Caddy，配置 HTTP 基本认证（Basic Auth）或集成 OAuth。
   • 仅在内网使用：在家庭局域网或 VPN 后访问，这是最安全的方式。
3. 汇率 API：如果你需要多币种汇总功能，且项目默认没有内置免费汇率源，你需要自行申请一个汇率 API 的密钥，并通过环境变量或配置文件注入到项目中。具体方式需参考项目源码的配置部分。

4.3 进阶使用技巧与数据迁移

1. 本地存储与服务端存储的切换：如果你一开始在本地浏览器中使用（USE_LOCAL_STORAGE=true），后来想迁移到自部署的服务端，可以这样做：

• 在浏览器中使用 Subs 的导出（Export）功能，下载一个subscriptions.json文件。
• 将部署好的服务端 Subs 运行起来。
• 在服务端 Subs 界面，使用导入（Import）功能，上传刚才下载的 JSON 文件。 这样就完成了数据迁移。反之亦然。

2. 键盘快捷键的肌肉记忆：养成使用快捷键的习惯能极大提升操作效率。尤其是n（新建）和/（搜索），是使用频率最高的两个操作。你可以把?快捷键的帮助面板当作一个随时可查的备忘单。

3. JSON 数据的手动编辑：对于高级用户，你可以直接编辑data/config.json文件来批量修改订阅。文件结构是明文的 JSON，可读性很强。但在编辑前，务必停止 Subs 服务或确保没有正在写入的操作，并做好备份，以免损坏数据格式导致应用无法读取。

5. 常见问题排查与开发者贡献指南

5.1 使用与部署问题速查表

5.2 为开源项目贡献代码

如果你在使用中发现 Bug，或者有很棒的新功能想法，非常欢迎向 Subs 项目贡献代码。流程是标准的 GitHub 协作模式：

1. Fork 仓库：在 GitHub 上点击项目页面的 “Fork” 按钮，创建你自己的副本。
2. 克隆与分支：

   git clone https://github.com/你的用户名/subs.git cd subs git checkout -b feat/your-feature-name # 创建功能分支

3. 开发与测试：进行代码修改。务必确保新功能有相应的测试（如果是功能代码，添加 Playwright E2E 测试；如果是工具函数，添加单元测试）。在提交前，运行项目提供的检查脚本：

   npm run typecheck # 确保 TypeScript 类型正确 npm run lint # 确保代码风格符合 Biome 规范 npm run test # 确保所有测试通过

4. 提交与推送：

   git add . git commit -m "feat: 添加了XXX功能" # 使用清晰的提交信息 git push origin feat/your-feature-name

5. 发起 Pull Request (PR)：回到 GitHub 上你的仓库页面，通常会有一个提示让你为你刚推送的分支创建 PR。点击后，选择向原仓库（ajnart/subs）的main分支发起合并请求。在 PR 描述中，详细说明你的修改内容、动机以及测试情况。

给贡献者的建议：在开始开发新功能前，最好先在项目的 Issue 列表里查看是否有相关讨论，或者新建一个 Issue 描述你的想法，与维护者（我）达成共识后再动手，这样可以避免重复劳动或方向偏差。