116 lines
2.8 KiB
Markdown
116 lines
2.8 KiB
Markdown
# asset-tracker
|
||
|
||
个人资产管理系统（MVP）
|
||
|
||
## MVP 范围
|
||
|
||
- 用户登录鉴权（JWT）
|
||
- 资产分类管理（分类列表/新增）
|
||
- 资产管理（新增/列表/更新/删除）
|
||
- 仪表盘汇总（总资产、分类占比、未来30天到期）
|
||
- 到期提醒（预生成 reminders + 定时扫描发送状态）
|
||
|
||
## 技术栈
|
||
|
||
- Go 1.22+
|
||
- Gin
|
||
- GORM + SQLite
|
||
- robfig/cron
|
||
|
||
## 快速启动
|
||
|
||
```bash
|
||
cd asset-tracker
|
||
go mod tidy
|
||
go run ./cmd/server
|
||
```
|
||
|
||
服务默认监听：`http://127.0.0.1:9530`
|
||
|
||
默认账号（首次启动自动创建）：
|
||
- username: `admin`
|
||
- password: `admin123`
|
||
|
||
> 强烈建议通过环境变量覆盖：`DEFAULT_USERNAME` `DEFAULT_PASSWORD` `JWT_SECRET`
|
||
|
||
## 鉴权流程
|
||
|
||
1. `POST /api/v1/auth/login` 获取 `access_token`（`refresh_token` 写入 HttpOnly Cookie）
|
||
2. 后续请求添加 Header：`Authorization: Bearer <access_token>`
|
||
3. access 过期后调用 `POST /api/v1/auth/refresh`（优先用 Cookie 刷新）
|
||
|
||
## 错误响应结构（统一）
|
||
|
||
```json
|
||
{
|
||
"code": "ASSET_INVALID_STATUS",
|
||
"message": "status must be active or inactive",
|
||
"details": null,
|
||
"request_id": "d3f4a1b2c3d4e5f6"
|
||
}
|
||
```
|
||
|
||
所有响应都会带 `X-Request-Id`，便于日志排查。
|
||
|
||
## 关键接口
|
||
|
||
- `POST /api/v1/auth/login`
|
||
- `POST /api/v1/auth/refresh`
|
||
- `POST /api/v1/categories`
|
||
- `GET /api/v1/categories`
|
||
- `POST /api/v1/assets`
|
||
- `GET /api/v1/assets?page=1&page_size=20&status=active`
|
||
- `PUT /api/v1/assets/:id`
|
||
- `DELETE /api/v1/assets/:id`
|
||
- `GET /api/v1/dashboard/summary`
|
||
- `GET /api/v1/reminders?status=failed&page=1&page_size=20`
|
||
- `GET /healthz`
|
||
- `GET /readyz`
|
||
|
||
详细 API 见：`openapi.yaml`
|
||
|
||
## 生产部署必备项清单
|
||
|
||
- [ ] 设置强 JWT 密钥（`JWT_SECRET`），禁止使用默认值
|
||
- [ ] `APP_ENV=production`（生产环境会强校验 JWT_SECRET）
|
||
- [ ] 配置 `ACCESS_TTL_MINUTES`、`REFRESH_TTL_HOURS`（按安全策略）
|
||
- [ ] 启用服务守护（systemd 或 docker compose restart）
|
||
- [ ] 开启健康检查（`/healthz`）与日志采集
|
||
- [ ] 使用 HTTPS 反向代理（确保 Cookie `Secure` 生效）
|
||
|
||
### systemd 快速部署
|
||
|
||
```bash
|
||
cd /root/.openclaw/workspace/asset-tracker
|
||
cp .env.production.example .env.production
|
||
# 编辑 .env.production，设置强 JWT_SECRET
|
||
|
||
bash deploy/systemd/install_systemd.sh
|
||
systemctl enable --now asset-tracker
|
||
systemctl status asset-tracker --no-pager
|
||
```
|
||
|
||
### Docker Compose 生产部署
|
||
|
||
```bash
|
||
cd /root/.openclaw/workspace/asset-tracker/deploy
|
||
export JWT_SECRET='replace_with_strong_random_secret'
|
||
docker compose up -d --build
|
||
```
|
||
|
||
## 备份与恢复
|
||
|
||
```bash
|
||
# 备份
|
||
DB_PATH=./data/asset-tracker.db ./scripts/backup_db.sh
|
||
|
||
# 恢复
|
||
./scripts/restore_db.sh ./backups/asset-tracker-YYYYmmdd_HHMMSS.db.gz ./data/asset-tracker.db
|
||
```
|
||
|
||
## 后续建议
|
||
|
||
- 真实通知通道（Telegram/邮件）
|
||
- 估值快照与趋势图
|
||
- 多币种折算
|