caojia
58 lines
3.1 KiB
Markdown
58 lines
3.1 KiB
Markdown
# 应收账单 OSS 存储
|
||
|
||
新生成的应收账单导出 Excel 上传到 `lionqueen` Bucket。
|
||
生产路径为 `bms/prod/ar/bill/yyyy/MM/dd/<uuid>.xlsx`，本地、测试路径为
|
||
`bms/test/ar/bill/yyyy/MM/dd/<uuid>.xlsx`。数据库 `ar_bill_detail_export.storage_key`
|
||
保存包含完整对象路径的 `oss://lionqueen/...`，不需要数据库变更。
|
||
生产环境启动需启用 `prod` Profile，可通过 `OSS_PATH_PREFIX` 覆盖目录前缀
|
||
（不以 `/` 开头或结尾）。同 Bucket 下的目录划分用于区分文件，权限隔离仍需配置 RAM 策略。
|
||
|
||
## 部署配置
|
||
|
||
在后端进程环境变量中填写完整密钥，然后重启后端：
|
||
|
||
```text
|
||
OSS_ACCESS_KEY_ID=<完整 AccessKey ID>
|
||
OSS_ACCESS_KEY_SECRET=<完整 AccessKey Secret>
|
||
```
|
||
|
||
默认配置位于 `bms-admin/src/main/resources/application.yml`：
|
||
|
||
```yaml
|
||
oss:
|
||
endpoint: ${OSS_ENDPOINT:https://oss.lionquexpress.com}
|
||
bucket: ${OSS_BUCKET:lionqueen}
|
||
path-prefix: ${OSS_PATH_PREFIX:bms/test}
|
||
cname: ${OSS_CNAME:true}
|
||
access-key-id: ${OSS_ACCESS_KEY_ID:}
|
||
access-key-secret: ${OSS_ACCESS_KEY_SECRET:}
|
||
```
|
||
|
||
也可以通过外部 Spring 配置文件填写这些配置。
|
||
`oss.lionquexpress.com` 按 OSS 自定义域名使用，需在 OSS 控制台已绑定到
|
||
`lionqueen`，且 HTTPS 证书可用。若这个域名仅用于 CDN 分发，请设置
|
||
`OSS_ENDPOINT` 为 Bucket 所在地域的 OSS Endpoint，并设置 `OSS_CNAME=false`。
|
||
密钥需要目标 Bucket 下对应对象的上传、读取、删除权限。
|
||
|
||
## 生成和下载
|
||
|
||
- 流式生成系统临时文件，计算大小和 SHA-256，上传成功后才更新导出状态为 SUCCESS。
|
||
- 上传时显式设置对象 ACL 为 private，下载继续使用原有账单下载接口及权限校验，后端流式读取 OSS。
|
||
- 生成或上传失败走原有 FAILED 状态处理；正常和异常路径都会尝试清理临时文件。
|
||
- 任务已超时或被其他流程结束、成功状态更新返回 0 时，删除该次上传的 OSS 对象。
|
||
- OSS 上传与数据库状态更新不属于同一事务；数据库更新异常可能留下未关联的 OSS 对象，需运维核对处理。
|
||
- 历史 `/profile/...` 账单仍从原本地目录下载，本次不迁移历史文件。
|
||
- 已有 `oss://lionqueen/bms/ar/bill/...` 文件仍按数据库中记录的路径读取，下载和删除不重新添加环境前缀。
|
||
- 普通附件、头像、导入文件及导出模板维持现有存储方式。
|
||
|
||
SDK 自定义域名与客户端配置参考：[阿里云 OSS Java SDK 文档](https://www.alibabacloud.com/help/en/oss/developer-reference/oss-java-sdk/)。
|
||
|
||
## 毛利分析报表
|
||
|
||
产品、订单两个维度的导出也使用上述 OSS 配置。生产文件路径为
|
||
`bms/prod/report/profit/yyyy/MM/dd/<uuid>.xlsx`，本地和测试为
|
||
`bms/test/report/profit/yyyy/MM/dd/<uuid>.xlsx`。
|
||
导出保持同步：临时 Excel 生成并上传成功后更新导出日志，再由前端发起下载。
|
||
下载继续校验当前用户及原接口权限；历史本地文件名仍从原 download 目录读取。
|
||
上传失败标记导出失败并清理临时文件，状态更新返回 0 时删除此次上传的 OSS 对象。
|