98 lines
6.6 KiB
Cheetah
98 lines
6.6 KiB
Cheetah
# 按需装配的日志与文件模块
|
||
|
||
本项目选用日志输出 `{{.LogOutput}}`、格式 `{{.LogFormat}}`、对象存储 `{{.Storage}}`。数据库选择 `{{.Database}}` 独立于对象存储。
|
||
|
||
配置入口为 `etc/config.yaml`，通过 `go run ./cmd/server -config /path/to/config.yaml` 指定其他 JSON/YAML 文件；`-config ''` 只用代码默认值和环境变量。优先级：默认值 → 文件 → 非空环境变量。未知字段、无效参数会在监听前拒绝。
|
||
|
||
```sh
|
||
go mod tidy
|
||
{{if ne .Storage "none"}}# 示例文件接口使用单一共享 Token，不是用户/租户权限系统。
|
||
export GO_OMNI_FILES_TOKEN="$(openssl rand -hex 32)"
|
||
{{if eq .Storage "local"}}# 本地签名密钥需要稳定保存；换密钥后旧链接失效。
|
||
export GO_OMNI_STORAGE_SIGNING_KEY="$(openssl rand -hex 32)"
|
||
{{else}}# 配置当前存储平台已有的桶和凭据，不会自动创建桶。
|
||
export GO_OMNI_STORAGE_BUCKET='your-bucket'
|
||
export GO_OMNI_STORAGE_ACCESS_KEY='your-access-key'
|
||
export GO_OMNI_STORAGE_SECRET_KEY='your-secret-key'
|
||
{{if eq .Storage "s3"}}export GO_OMNI_STORAGE_ENDPOINT='s3.us-east-1.amazonaws.com'
|
||
export GO_OMNI_STORAGE_REGION='us-east-1'
|
||
{{else if eq .Storage "r2"}}export GO_OMNI_STORAGE_ACCOUNT_ID='your-32-character-account-id'
|
||
{{else}}export GO_OMNI_STORAGE_REGION='cn-hangzhou'
|
||
{{end}}{{end}}{{end}}
|
||
go run ./cmd/server
|
||
```
|
||
|
||
{{if eq .Database "mysql"}}还需按 README 配置独立 MySQL 数据库并应用 schema.sql；应用不自动迁移。{{end}}
|
||
|
||
默认仅监听 `127.0.0.1:8080`。`GO_OMNI_HTTP_ADDR` 覆盖地址；本地签名 URL 的外部地址通过 `GO_OMNI_STORAGE_PUBLIC_URL` 单独配置，始终以 `/storage/object` 结尾，不使用请求 Host 自动拼接可信链接。
|
||
|
||
## 日志
|
||
|
||
业务示例在创建用户/上传文件成功时通过 logx 写结构化日志。Context 原样传递 requestId，框架不自动增加用户、租户等业务字段。文件模式已配置轮转：100 MiB、10 份、7 天、压缩。调整 `server.log` 即可更改；`redactKeys` 可增加业务敏感键。
|
||
|
||
```sh
|
||
curl -H 'Content-Type: application/json' -H 'X-Request-ID: example-request' \
|
||
-d '{"name":"Example","email":"example@example.com"}' http://127.0.0.1:8080/users
|
||
```
|
||
|
||
`GO_OMNI_LOG_LEVEL`、`GO_OMNI_LOG_FORMAT`、`GO_OMNI_LOG_FILE` 覆盖对应项；显式设置 `GO_OMNI_LOG_OUTPUT=stdout` 且未设置 LOG_FILE 时，切换到控制台并关闭文件轮转。慢请求阈值为 500ms，可通过 `GO_OMNI_SLOW_REQUEST_THRESHOLD` 调整。字段脱敏不扫描 msg/error 中的自由文本；不要把凭据或签名 URL 拼到日志中。
|
||
|
||
{{if ne .Storage "none"}}## 文件示例
|
||
|
||
Handler → Service → storage 接口；底层构造与连接池集中在 `internal/servicecontext/storage.go`。示例接口要求 `Authorization: Bearer $GO_OMNI_FILES_TOKEN`，它授权这个示例的全部文件，实际业务应替换认证和对象归属检查。存储适配器不承担业务授权。
|
||
|
||
```sh
|
||
printf 'hello go-omni' > /tmp/goOmniExample.txt
|
||
curl -H "Authorization: Bearer $GO_OMNI_FILES_TOKEN" \
|
||
-H 'Content-Type: text/plain' -H 'X-Request-ID: file-example' \
|
||
--data-binary @/tmp/goOmniExample.txt http://127.0.0.1:8080/files
|
||
```
|
||
|
||
保存响应中 `data.key`，再请求下载链接（把示例 key 替换为返回值）：
|
||
|
||
```sh
|
||
curl -H "Authorization: Bearer $GO_OMNI_FILES_TOKEN" -H 'Content-Type: application/json' \
|
||
-d '{"key":"uploads/returned-key"}' http://127.0.0.1:8080/files/downloadLink
|
||
```
|
||
|
||
返回 `data.url`，在有效期内 GET 即可下载，无需再携带 Token。签发前会检查对象存在；URL 默认 5 分钟有效，不写日志，响应设置 no-store。
|
||
|
||
需要直传时先申请链接：
|
||
|
||
```sh
|
||
curl -H "Authorization: Bearer $GO_OMNI_FILES_TOKEN" -H 'Content-Type: application/json' \
|
||
-d '{"size":13,"contentType":"text/plain"}' http://127.0.0.1:8080/files/uploadLink
|
||
```
|
||
|
||
响应包括随机 `data.key` 和 `data.request`（method/url/headers/expiresAt）。按返回的 method 和 headers 用原始文件字节上传到 URL；不能额外包 FormData。浏览器自动填写 Content-Length，其余签名 Header 原样发送；云桶需配置允许业务域名的 CORS。云端直传只绑定声明类型，实际内容需上传后验证；本地和 API 中转上传会检查允许类型及前缀嗅探结果。未完成内容验证前不要把暂存文件当作可信文件公开。
|
||
|
||
| 参数 | 默认值 / 环境变量 |
|
||
| --- | --- |
|
||
| 大小 | 32 MiB / GO_OMNI_STORAGE_MAX_BYTES |
|
||
| 类型 | text/plain、image/png、image/jpeg、application/pdf / GO_OMNI_STORAGE_CONTENT_TYPES（逗号分隔） |
|
||
| 链接有效期 | 5m / GO_OMNI_STORAGE_LINK_TTL（1s..1h） |
|
||
| 请求超时 | 30s / GO_OMNI_STORAGE_REQUEST_TIMEOUT（>0 且 <=5m） |
|
||
| 本地目录 | var/files / GO_OMNI_STORAGE_ROOT |
|
||
| 本地外部 URL | http://127.0.0.1:8080/storage/object / GO_OMNI_STORAGE_PUBLIC_URL |
|
||
| 云配置 | GO_OMNI_STORAGE_ENDPOINT、REGION、BUCKET、ACCOUNT_ID、SECURE |
|
||
| 环境密钥 | GO_OMNI_FILES_TOKEN、GO_OMNI_STORAGE_SIGNING_KEY、GO_OMNI_STORAGE_ACCESS_KEY、SECRET_KEY、SESSION_TOKEN |
|
||
|
||
全部 JSON/YAML 字段使用 lowerCamelCase。密钥字段仅允许环境变量，配置文件中写入会报未知字段；不要把运行环境文件提交到仓库。S3 的 endpoint 为 host[:port]，OSS 的可选 endpoint 为 HTTPS origin；R2 从 accountId 派生官方 endpoint，region 为 auto。仅 S3/MinIO 的本地测试可设置 SECURE=false。
|
||
|
||
错误响应：未授权 401、无 Content-Length 411、超限 413、类型不允许 415、长度不符/非法 key 400、对象不存在 404、存储超时 504，其余内部错误统一隐藏细节。底层签名入口遵循存储协议返回 201/403 等状态，流式传输且访问日志保留实际状态。
|
||
|
||
云客户端只在组合处创建，使用专用有界连接池；配置正确不代表桶和网络已经可用，首次真实调用仍可能失败。不创建桶、不修改桶权限、不初始化任何业务数据库。更换平台时替换组合处适配器，业务 Service 接口保持不变。
|
||
{{end}}
|
||
|
||
## 生命周期与验证
|
||
|
||
启动失败会清理已创建资源；SIGINT/SIGTERM 后先等待 HTTP 请求退出，再关闭服务依赖，最后关闭日志。只关闭项目自己创建的资源，不关闭全局默认 HTTP Transport。
|
||
|
||
```sh
|
||
go test -race ./...
|
||
go build -o server ./cmd/server
|
||
./server
|
||
```
|
||
|
||
生成的测试覆盖配置优先级/校验{{if ne .Storage "none"}}、资源关闭幂等性和借用日志所有权、上传与临时链接、签名篡改、限额/类型错误。业务测试使用临时 Local，不访问云账号；云端配置需另做实网验收{{end}}。基础用户 CRUD 示例仍未启用认证，部署前按业务需要替换。
|