3.3 KiB
cmroubao backend API
Go 1.23.0、Gin 1.11.0 和 SQLite 构成的单进程采购任务服务。当前提供参考图上传与 规范化、任务创建/列表/详情/取消 API、服务端渲染管理页面、健康检查和显式数据库 迁移，并使用 ADMIN 服务端会话和 BUYER + 预授权设备联合身份隔离管理与执行接口。
环境
- Go 1.23.0
CGO_ENABLED=1- PATH 中可用的 GCC
可选环境变量：
| 变量 | 默认值 | 说明 |
|---|---|---|
CMROUBAO_HTTP_ADDR |
127.0.0.1:8080 |
监听地址；无 TLS 时只允许 loopback |
CMROUBAO_DATABASE_PATH |
var/cmroubao.db |
SQLite 文件路径 |
CMROUBAO_ASSET_DIR |
var/assets |
规范化参考图片的受控本地目录 |
CMROUBAO_TLS_CERT_FILE |
无 | TLS certificate；必须和 private key 同时设置 |
CMROUBAO_TLS_KEY_FILE |
无 | TLS private key；非 loopback 监听必须设置 |
不会自动读取 .env。本地配置和 var/ 运行数据不得提交。
命令
$env:GOTOOLCHAIN = "local"
go test ./...
go vet ./...
go build -o bin/cmroubao-api.exe ./cmd/api
go build -o bin/cmroubao-migrate.exe ./cmd/migrate
go build -o bin/cmroubao-authctl.exe ./cmd/authctl
go run ./cmd/migrate up
go run ./cmd/migrate status
$env:CMROUBAO_AUTH_PASSWORD = "至少 12 个 UTF-8 字节"
go run ./cmd/authctl create-user ADMIN admin
Remove-Item Env:CMROUBAO_AUTH_PASSWORD
go run ./cmd/authctl create-device buyer-phone-01
# 发生人员离岗或设备风险时，现有凭证会随禁用立即失效
go run ./cmd/authctl disable-user buyer01
go run ./cmd/authctl disable-device <device-id>
# 恢复时使用对应的 enable-user / enable-device
go run ./cmd/api
API 启动前会检查全部 migration 已应用；发现 pending migration 会拒绝启动并提示先
执行 go run ./cmd/migrate up，不会在服务进程内自动改表。
authctl create-user 的密码只从 CMROUBAO_AUTH_PASSWORD 读取，不接受命令行密码。
create-device 只在成功时输出一次设备 ID 和 256 bit 设备 token；原值应立即放入
设备安全配置，不得写入 Git、普通日志或共享文档。enable-user、disable-user、
enable-device、disable-device 是受支持的本地停用/恢复入口；禁用会让该主体的
现有 session/access token 在下一次请求时失效。
服务启动后，GET /healthz 在数据库可用时返回 200 和
{"status":"ok"}，不可用时返回 503 和 {"status":"unavailable"}。管理页面：
GET /tasks：任务列表、搜索和状态筛选。GET /tasks/new：上传参考图并创建任务。GET /tasks/{id}：查看原始约束和任务状态，待领取任务可取消。GET/POST /login、POST /logout：建立或撤销 8 小时 ADMIN 会话。
未登录管理页面会跳转 /login，未授权管理 API 返回 401。Cookie 认证的管理 API
写请求还需要 X-CSRF-Token。采购 App 使用 POST /api/v1/auth/token，ADMIN
Cookie 与 BUYER Bearer token 不能互换。两类登录在凭证校验前按来源地址独立限流：
5 分钟最多 10 次，超限返回 429 和 Retry-After，成功后清零。
默认 loopback 可使用 HTTP 开发。局域网监听必须同时设置 certificate/private key，
服务直接使用 TLS 启动，不会降级为明文。完整 API 合约见
../docs/api.md。