39 lines
1.9 KiB
Markdown
39 lines
1.9 KiB
Markdown
# Book & Comic Library
|
|
|
|
个人书库/漫画库:Go+Gin 后端(扫描/上传入库、多用户 JWT、阅读进度、磁盘+Redis 缓存)+ Docker Compose 部署。设计见 `docs/superpowers/specs/2026-09-04-book-comic-library-design.md`。
|
|
|
|
## 跑起来(生产形态)
|
|
|
|
```bash
|
|
cp .env.example .env # 填 JWT_SECRET、ADMIN_USER、ADMIN_PASSWORD(≥8 位,低于 8 位 seed 会跳过并 log)
|
|
docker compose up -d --build
|
|
./scripts/smoke.sh # 端到端验收(登录、建库、上传、扫描、进度、删除、immutable 头)
|
|
```
|
|
|
|
- web: `http://localhost:8080`,API 走 nginx `/api/` 前缀反代到无状态 api 副本(`--scale api=N`)。
|
|
- 原始书放在 `./library/`(挂到 `/data/books`),scanner 周期入库(默认 60s)。
|
|
|
|
## 可信代理与限流
|
|
|
|
- nginx 在 compose 网络内,api 的 `ClientIP` 只信 `TRUSTED_PROXY_CIDRS`(逗号分隔 CIDR,默认 `172.16.0.0/12`,即 compose 网段)。外部伪造 `X-Forwarded-For` 换不掉限流桶;换部署网络时改这个 env。
|
|
- 登录限流 5 次/分钟/IP **按尝试计数,成功登录也计**——爆破和正常高频登录同账。
|
|
|
|
## 开发 / 测试
|
|
|
|
```bash
|
|
docker compose -f deploy/docker-compose.dev.yml up -d # PG :5433, Redis :6380(避开本机默认端口)
|
|
cd backend
|
|
export DATABASE_URL='postgres://lib:lib@localhost:5433/lib?sslmode=disable'
|
|
export REDIS_URL='redis://localhost:6380'
|
|
go vet ./... && gofmt -l .
|
|
go test -p 1 -count=1 ./...
|
|
```
|
|
|
|
`-p 1` 是必须的:集成测试共用同一个 PG 库,各自 `DELETE FROM ...` 清表——并行跑会互相删数据导致随机失败。
|
|
|
|
无 PG/Redis 时依赖它们的测试自动 skip;Redis 挂掉不影响功能(全链路降级为 miss/放行,见 spec §9)。
|
|
|
|
## 改 schema 前必读
|
|
|
|
`db.Migrate` 只执行 `schema.sql` 的 `CREATE TABLE IF NOT EXISTS`——对已存在的库**加列/改列不会生效**。任何列变更之前,必须先引入 `schema_migrations` 版本表 + 有序迁移脚本,否则老部署会静默跑在旧结构上。
|