146 lines
5.0 KiB
Markdown
146 lines
5.0 KiB
Markdown
# Cents
|
||
|
||
家庭共享账本 App。
|
||
|
||
目标是做一个精简、可靠、可离线使用的手机应用，支持 Android 和 iOS。用户在无网络时也能记账，网络恢复后自动同步到家庭共享账本。
|
||
|
||
当前阶段：产品边界和技术设计。
|
||
|
||
- [产品边界](docs/产品边界.md)
|
||
- [技术方案](docs/技术方案.md)
|
||
- [数据与同步](docs/数据与同步.md)
|
||
- [账号与权限](docs/账号与权限.md)
|
||
- [测试策略](docs/测试策略.md)
|
||
- [内网穿透调试](docs/内网穿透调试.md)
|
||
- [HTML 原型图](docs/原型图/原型说明.md)
|
||
- [评审问题](docs/评审问题.md)
|
||
|
||
## 本地开发
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
`npm run dev` 会同时启动 API 和前端。前端运行在 `http://localhost:6064/`，并与 `compose.dev.yaml` 的 frp 调试入口保持一致。
|
||
|
||
常用检查：
|
||
|
||
```bash
|
||
npm run typecheck
|
||
npm run build
|
||
```
|
||
|
||
## 生产环境启动
|
||
|
||
在生产环境 clone 目录中更新代码。首次启动时从示例创建 `.env`；如果已经存在 `.env`，不要覆盖：
|
||
|
||
```bash
|
||
git pull
|
||
test -f .env || cp .env.example .env
|
||
```
|
||
|
||
编辑 `.env`，确认域名、frp 服务地址和数据库配置正确，并为 `POSTGRES_PASSWORD` 设置高强度密码：
|
||
|
||
```dotenv
|
||
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
|
||
```
|
||
|
||
构建并启动生产环境：
|
||
|
||
```bash
|
||
docker compose --env-file .env -f compose.pro.yaml up -d --build
|
||
```
|
||
|
||
检查容器状态和日志：
|
||
|
||
```bash
|
||
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`，否则会删除生产数据库卷：
|
||
|
||
```bash
|
||
docker compose --env-file .env -f compose.pro.yaml down
|
||
```
|
||
|
||
## 生产环境添加用户
|
||
|
||
生产环境通过 Docker Compose 在 API 容器内运行 npm 脚本，宿主机无需安装 Node.js 或 npm：
|
||
|
||
```bash
|
||
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` 时只保留本地备份。
|
||
|
||
```text
|
||
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，禁止密码登录。
|
||
|
||
首次启动备份容器前，先在宿主机手动连接一次，以核对并记录主机指纹：
|
||
|
||
```bash
|
||
ssh -p 22 backup@backup.example.com true
|
||
```
|
||
|
||
远端文件先以隐藏的临时文件上传，完成后再改为正式名称。远端 dump 同样保留 30 天；不会镜像删除本地目录中的其他内容。
|
||
|
||
查看调度和备份日志：
|
||
|
||
```bash
|
||
docker compose --env-file .env -f compose.pro.yaml logs -f backup
|
||
```
|
||
|
||
立即手动备份一次：
|
||
|
||
```bash
|
||
docker compose --env-file .env -f compose.pro.yaml exec backup \
|
||
/usr/local/bin/cents-backup run
|
||
```
|
||
|
||
备份文件位于宿主机：
|
||
|
||
```text
|
||
./backups/db/cents-YYYYMMDD-HHMMSS.dump
|
||
```
|
||
|
||
建议在首次部署及之后偶尔将最新 dump 恢复到临时数据库，确认备份实际可用：
|
||
|
||
```bash
|
||
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
|
||
```
|