Cents

家庭共享账本 App。

目标是做一个精简、可靠、可离线使用的手机应用，支持 Android 和 iOS。用户在无网络时也能记账，网络恢复后自动同步到家庭共享账本。

当前阶段：产品边界和技术设计。

• 产品边界
• 技术方案
• 数据与同步
• 账号与权限
• 测试策略
• 内网穿透调试
• HTML 原型图
• 评审问题

本地开发

npm install
npm run dev

npm run dev 会同时启动 API 和前端。前端运行在 http://localhost:6064/，并与 compose.dev.yaml 的 frp 调试入口保持一致。

常用检查：

npm run typecheck
npm run build

生产环境启动

在生产环境 clone 目录中更新代码。首次启动时从示例创建 .env；如果已经存在 .env，不要覆盖：

git pull
test -f .env || cp .env.example .env

编辑 .env，确认域名、frp 服务地址和数据库配置正确，并为 POSTGRES_PASSWORD 设置高强度密码：

DOMAIN=cents.homemade.net.cn
APP_VARIANT=pro
FRPC_SERVER_HOST=119.28.12.24
FRPC_SERVER_PORT=7000
TEST_MODE=false
POSTGRES_DB=cents
POSTGRES_USER=cents
POSTGRES_PASSWORD=replace-with-a-strong-password

构建并启动生产环境：

docker compose --env-file .env -f compose.pro.yaml up -d --build

检查容器状态和日志：

docker compose --env-file .env -f compose.pro.yaml ps
docker compose --env-file .env -f compose.pro.yaml logs -f api web frpc cert

后续更新同样执行 git pull 和 up -d --build，数据库卷会保留。停止环境时不要添加 -v，否则会删除生产数据库卷：

docker compose --env-file .env -f compose.pro.yaml down

生产环境添加用户

生产环境通过 Docker Compose 在 API 容器内运行 npm 脚本，宿主机无需安装 Node.js 或 npm：

docker compose --env-file .env -f compose.pro.yaml exec api \
  npm run user:add -- '用户名' '至少8位的密码'

用户与唯一的“个人账本”会在同一个数据库事务内创建。

生产数据库备份

backup 容器每天北京时间 02:00 使用 PostgreSQL custom format 执行一次逻辑备份，写入生产 clone 目录下的 ./backups/db。备份先写入临时文件，能够读取归档目录后再改为正式文件；dump 权限为 0600，超过 30 天自动删除。

当前应用的业务数据全部存放在 PostgreSQL 中，因此不备份运行中的 Docker volume。证书可以重新签发，代码由 Git 保存。若将来增加上传文件等数据库外的持久化数据，需要再单独备份对应目录。

备份成功后会更新 ./backups/.last-success。容器启动后的前 26 小时是健康检查宽限期，此后若定时器未运行，或超过 30 小时没有完整成功的备份，backup 容器会变为 unhealthy。

.env 不随数据库 dump 备份，其中的部署参数应另行保存在密码管理器等安全位置。

远程备份（可选）

远程服务器地址配置在生产部署使用的 .env 中。配置后，每次本地备份成功都会通过 SCP 上传本次新 dump；未配置 BACKUP_SSH_HOST 时只保留本地备份。

BACKUP_SSH_HOST=backup.example.com   # 置空则禁用远程备份
BACKUP_SSH_USER=backup               # 建议使用只管理备份目录的非 root 用户
BACKUP_SSH_PORT=22
BACKUP_SSH_DIR=/home/backup/cents    # 必须是非根绝对路径，不能包含空格

SCP 使用生产宿主机当前用户的 ~/.ssh，该目录以只读方式挂载到容器。建议为备份创建专用 SSH 密钥，并通过 ~/.ssh/config 为备份主机指定该密钥。身份验证强制使用 SSH key，禁止密码登录。

首次启动备份容器前，先在宿主机手动连接一次，以核对并记录主机指纹：

ssh -p 22 backup@backup.example.com true

远端文件先以隐藏的临时文件上传，完成后再改为正式名称。远端 dump 同样保留 30 天；不会镜像删除本地目录中的其他内容。

查看调度和备份日志：

docker compose --env-file .env -f compose.pro.yaml logs -f backup

立即手动备份一次：

docker compose --env-file .env -f compose.pro.yaml exec backup \
  /usr/local/bin/cents-backup run

备份文件位于宿主机：

./backups/db/cents-YYYYMMDD-HHMMSS.dump

建议在首次部署及之后偶尔将最新 dump 恢复到临时数据库，确认备份实际可用：

docker compose --env-file .env -f compose.pro.yaml exec db \
  createdb -U cents cents_restore
docker compose --env-file .env -f compose.pro.yaml exec backup \
  pg_restore --dbname=cents_restore /backups/db/cents-YYYYMMDD-HHMMSS.dump
docker compose --env-file .env -f compose.pro.yaml exec db \
  dropdb -U cents cents_restore