nl-pms-api/README.md

nl-pms-api

code-count（view 桌面端）的文件存储服务：客户端凭密钥上传图片，换取可公开访问的 http URL。管理员（云端账号 id=1）在 view 的「文件存储」配置里把存储方式设为 「服务器」并填入本服务地址与密钥后，内容图片（imageMode=server）与头像会上传到 这里，Markdown / 头像直接引用返回的 URL —— 跨设备、跨团队都能访问，不再依赖本地路径。

技术栈：Go + gin + gorm，MySQL 与 view 同步服务共用 code_count 库（新表 pms_files）。

接口

方法	路径	鉴权	说明
GET	/healthz	无	健康检查（view「测试连接」调用）
POST	/api/v1/files	Authorization: Bearer <api_key>	multipart 上传：file 必填，kind（avatar|content）、userId、teamId 可选；返回 {id, name, url, size, mime, teamId}
GET	/api/v1/files	同上	素材库列表：scope=mine|team|all + userId + teamId + page + pageSize；mine 看自己，team 需为该团队 owner/admin，all 仅超管（userId=1）；返回 {total, items}（含上传者 username）
DELETE	/api/v1/files/:id	同上	删除素材（记录+磁盘文件）：本人、超管 id=1、或该文件归属团队的 owner/admin
GET	/files/*path	无	文件公开访问（路径含 128 位随机 hex，不可枚举）

上传约束：默认单文件 ≤ 20MB（max_upload_mb）；按内容嗅探只接受 jpeg/png/gif/webp； 同一归属（userId+teamId）重复上传相同内容直接复用已有记录（秒传）， 不同归属各自落盘，保证删除自己的素材不影响他人引用。

身份模型：沿用 code-count 的内网信任模型 —— 客户端自报 userId/teamId， 服务端按 code_count 库的 team_members/users 判定管理范围（防误操作，不防伪造）。

curl http://127.0.0.1:8788/healthz
curl -H "Authorization: Bearer change-me" -F "file=@a.png" -F "kind=content" \
     http://127.0.0.1:8788/api/v1/files

配置

复制 config.example.yaml 为 config.yaml 后修改（启动可用 -config 指定路径）。 必填：api_key（客户端上传密钥）、mysql.dsn；base_url 建议填客户端可达的地址， 留空则按请求 Host 推断。

数据库迁移约定（重要）

• 仅 dev 环境自动迁移：config.yaml 里 env: dev 时，启动执行 AutoMigrate。
• 生产绝不迁移：env: prod（默认）启动只检查 pms_files 表是否存在， 缺表直接报错退出，不执行任何 DDL。部署 / 升级前先手工执行：

mysql -u root -p < init.sql

init.sql 可重复执行（CREATE TABLE IF NOT EXISTS），索引名与 gorm 默认命名一致， 避免 dev / prod 两套 schema 漂移。

运行

# 开发（自动迁移）
go run . -config config.yaml     # config.yaml 里 env: dev

# 生产（先执行 init.sql，再构建部署）
go build -o bin/nl-pms-api .     # Windows 产出 bin/nl-pms-api.exe
./bin/nl-pms-api -config /etc/nl-pms-api/config.yaml

Windows 可用 nssm / 计划任务托管，Linux 建议 systemd；服务本身无状态， 备份只需 uploads/ 目录与 pms_files 表。

安全权衡（内网定位）

• 上传密钥经 view 的 sync_settings 明文下发给所有登录客户端（与节日背景图同机制）， 按内网工具定位设计；暴露公网需自行加 HTTPS 反代与更强的凭证体系。
• 图片 GET 公开：<img> 标签无法携带鉴权头，靠随机路径保证不可枚举。