《Postcat (邮递猫) 产品文档》

1. 项目用途与定位

Postcat (邮递猫) 是一个部署在 Netlify 平台的、完全无服务器 (Serverless) 的轻量级订阅管理面板。

• 核心目标: 为个人或小团体提供一个零运维成本的自动化订阅管理解决方案。
• 产品形态: 包含功能完善的用户前端和独立管理后台。

2. 核心功能

2.1. 用户端 (Frontend)

用户通过专属的“取件码”登录，无需注册。

• 仪表盘:
  • 以图形化方式展示流量使用情况（已用、剩余、总量）。
  • 显示订阅到期时间和下次流量重置时间。
  • 提供“一键导入”、“复制订阅链接”和“显示二维码”功能。
  • 展示当前用户可见的节点列表，并以星标（★）突出优化线路。
• 软件安装:
  • 提供跨平台（Mac, Windows, 安卓, iOS 等）的图文安装教程。
  • 教程内容由管理员在后台动态配置。
• 修改资料:
  • 用户可自行修改自己的“昵称”和“取件码”。
• 公告: 在用户登录后的首页，会显示由管理员发布的全局公告。

2.2. 管理后台 (Admin)

管理员通过独立的账号密码登录。

• 用户管理: 对用户进行完整的增删改查（CRUD）操作。可以设置用户的昵称、取件码、状态（正常/过期/停用）、所属用户组、全局端口、外部流量API，并能为特定节点覆写端口。
• 用户组管理: 创建或管理用户组，用于对用户和节点进行归类。
• 节点管理: 对节点进行 CRUD 操作。可以设置节点名称、服务器地址、是否为优化线路（星标），并将其绑定到一个或多个用户组。
• 配置模板管理:
  • 创建和管理两种类型的模板：节点片段 (Node Snippet) 和 订阅骨架 (Subscription Skeleton)。
  • 节点片段用于快速创建格式统一的节点；订阅骨架用于生成最终的订阅文件结构。
• 软件安装管理: 为前端的“软件安装”页面配置不同平台的图文教程，支持 Markdown 和多图片链接。
• 公告管理: 发布和修改显示在用户端的全局公告，支持 Markdown。
• 系统设置:
  • 修改管理员账号和密码。
  • 关联不同用户状态（正常/停用/过期）所使用的“订阅骨架”模板。
  • 配置前台页脚版权文案。
• 系统维护: 提供数据一致性检查、清理过期锁、清理孤儿数据和重建索引等高级维护功能。

3. 技术架构与后台设计

3.1. 技术栈

• 前端: Vite + React 18 + TypeScript + Tailwind CSS。
• 后端: Netlify Functions (基于 Node.js/TypeScript)。
• 数据存储: Netlify KV (底层为 Netlify Blobs)。
• 部署: 通过 Git Push 触发 Netlify CI/CD 自动构建和部署。

3.2. 数据流与路由

项目的核心运行机制是无服务器的，数据流如下： 用户/管理员 -> 浏览器 -> Netlify CDN -> Netlify Functions API -> Netlify KV 数据库

• API 路由: 所有对 /api/* 的前端请求，都会被 public/_redirects 文件中的规则 /api/* /.netlify/functions/:splat 200 透明地重定向到 netlify/functions/ 目录下对应的后端云函数执行。例如，对 /api/admin-users 的请求会由 netlify/functions/admin-users.ts 文件处理。

3.3. 核心后端逻辑：订阅生成 (sub.ts)

这是整个项目的业务核心，负责动态生成用户的订阅文件。

1. 用户定位: 通过订阅链接中的密钥 k 或备用取件码 code 在数据库中找到用户。
2. 状态检查: 判断用户是否为“停用”或“过期”状态，如果是，则返回预设的提示性配置。
3. 节点筛选与渲染: 根据用户所属的用户组，从所有节点中筛选出该用户可见的节点。然后将节点信息（如服务器、端口）填入该节点的“节点片段”模板中，生成最终的节点配置列表 (proxies)。
4. 骨架渲染: 获取“正常”状态的“订阅骨架”模板，并将上一步生成的节点列表 (proxies)、用户流量信息等，精确替换掉骨架中的占位符（如 {{PROXIES}}）。
5. 生成响应: 返回最终的 YAML 配置文件，并附带包含流量信息的 Subscription-Userinfo HTTP Header 供客户端读取。

4. 数据库 (Netlify KV) 结构设计

为了实现高效查询，系统采用了索引和实体分离的存储模式。所有数据均以 JSON 格式存储。

• 键 (Key) 设计模式:

  • [type]/index: 存储一个对象数组，包含核心字段，用于列表页快速展示和搜索。
  • [type]/by-id/{id}: 存储该 ID 对应的完整对象数据。
  • [type]/by-[field]/{value}: 通过特定字段快速定位数据的快捷方式，例如 users/by-code/{code}。

• 核心数据结构示例:

  • User (users/):

    • users/index: [{ id, nickname, code, status, ... }] 数组。
    • users/by-id/{id}: 包含用户所有信息的完整对象，如 nickname, code, port, status, api, groupIds 等。
    • users/by-code/{code}: 通过取件码快速查找用户。
    • users/by-subkey/{key}: 通过订阅密钥快速查找用户。

  • Node (nodes/):

    • nodes/index: [{ id, name, starred, groupIds }] 数组。
    • nodes/by-id/{id}: 包含节点完整信息，如 name, server, snippet 等。

  • Settings (settings/main): 存储系统级配置的单个 JSON 对象，如管理员账号 (adminUser)、密码哈希 (adminPassHash)、各状态模板ID等。