Compare commits
3 Commits
6041bc3419
...
0d57450283
| Author | SHA1 | Date | |
|---|---|---|---|
 shanshanzhong147
|
0d57450283 | ||
|
shanshanzhong147
|
f2033fd4b9 | ||
|
shanshanzhong147
|
3284cb45f0 |
@@ -5,9 +5,11 @@ on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
- internal
|
||||
pull_request:
|
||||
branches:
|
||||
- main
|
||||
- internal
|
||||
|
||||
env:
|
||||
# Docker镜像仓库
|
||||
@@ -53,7 +55,7 @@ jobs:
|
||||
elif [ "${{ github.ref_name }}" = "internal" ]; then
|
||||
echo "DOCKER_TAG_SUFFIX=internal" >> $GITHUB_ENV
|
||||
echo "CONTAINER_NAME=ppanel-server-internal" >> $GITHUB_ENV
|
||||
echo "DEPLOY_PATH=/root/hifast" >> $GITHUB_ENV
|
||||
echo "DEPLOY_PATH=/root/bindbox" >> $GITHUB_ENV
|
||||
echo "为 internal 分支设置开发环境变量"
|
||||
else
|
||||
echo "DOCKER_TAG_SUFFIX=${{ github.ref_name }}" >> $GITHUB_ENV
|
||||
|
||||
@@ -11,6 +11,20 @@ info (
|
||||
import "../types.api"
|
||||
|
||||
type (
|
||||
FileUploadRequest {
|
||||
BizType string `form:"biz_type" validate:"required"`
|
||||
}
|
||||
|
||||
FileUploadResponse {
|
||||
FileId string `json:"file_id"`
|
||||
FileName string `json:"file_name"`
|
||||
ObjectKey string `json:"object_key"`
|
||||
Size int64 `json:"size"`
|
||||
ContentType string `json:"content_type"`
|
||||
Etag string `json:"etag"`
|
||||
Status string `json:"status"`
|
||||
}
|
||||
|
||||
FileUploadInitRequest {
|
||||
BizType string `json:"biz_type" validate:"required"`
|
||||
FileName string `json:"file_name" validate:"required"`
|
||||
@@ -48,6 +62,10 @@ type (
|
||||
middleware: AuthMiddleware,DeviceMiddleware
|
||||
)
|
||||
service ppanel {
|
||||
@doc "Upload file to RustFS"
|
||||
@handler FileUpload
|
||||
post /upload (FileUploadRequest) returns (FileUploadResponse)
|
||||
|
||||
@doc "Init file upload"
|
||||
@handler FileUploadInit
|
||||
post /upload/init (FileUploadInitRequest) returns (FileUploadInitResponse)
|
||||
|
||||
@@ -0,0 +1,184 @@
|
||||
# TAPI 文件上传接入说明
|
||||
|
||||
本文档说明 `https://tapi.hifast.biz/v1/public/file/upload` 相关上传接口的推荐接入方式、签名规则与常见排查方式。
|
||||
|
||||
## 总览
|
||||
|
||||
上传能力包含两类接入方式：
|
||||
|
||||
- 推荐方式：`init -> S3 PUT -> complete`
|
||||
- 兼容方式：`/upload` multipart 直传
|
||||
|
||||
推荐优先使用预签名三段式，因为：
|
||||
|
||||
- 现有签名串包含 `BODY_SHA256`
|
||||
- `/upload` 是 `multipart/form-data`
|
||||
- multipart 原始 body 的签名和调试成本更高
|
||||
- `init` 和 `complete` 是 JSON，更适合客户端和 Apifox 调试
|
||||
|
||||
## 签名生效逻辑
|
||||
|
||||
项目保持现有旧逻辑，不做强制签名改造：
|
||||
|
||||
- `Signature.EnableSignature = false` 时：不校验签名
|
||||
- `Signature.EnableSignature = true` 且未携带 `X-App-Id` 时：不校验签名，兼容老客户端
|
||||
- `Signature.EnableSignature = true` 且携带 `X-App-Id` 时：必须同时携带并校验
|
||||
- `X-Timestamp`
|
||||
- `X-Nonce`
|
||||
- `X-Signature`
|
||||
|
||||
这意味着：
|
||||
|
||||
- 新客户端建议始终带完整签名头
|
||||
- 老客户端如果没有 `X-App-Id`，仍可按旧逻辑访问
|
||||
|
||||
## 签名头定义
|
||||
|
||||
- `X-App-Id`: 客户端标识，例如 `ios-client`
|
||||
- `X-Timestamp`: Unix 秒级时间戳
|
||||
- `X-Nonce`: 每次请求唯一随机串
|
||||
- `X-Signature`: `HMAC-SHA256` 结果的十六进制小写字符串
|
||||
|
||||
## StringToSign 规则
|
||||
|
||||
StringToSign 由下面 7 段按换行符 `\n` 拼接：
|
||||
|
||||
```text
|
||||
METHOD
|
||||
PATH
|
||||
CANONICAL_QUERY
|
||||
BODY_SHA256
|
||||
X-App-Id
|
||||
X-Timestamp
|
||||
X-Nonce
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `METHOD`：HTTP 方法大写，例如 `POST`
|
||||
- `PATH`：请求路径，例如 `/v1/public/file/upload/init`
|
||||
- `CANONICAL_QUERY`：按 key 排序后的 query string，没有 query 则为空字符串
|
||||
- `BODY_SHA256`：请求体原始字节的 SHA-256 十六进制小写
|
||||
- 其余三项直接使用请求头值
|
||||
|
||||
签名计算方式：
|
||||
|
||||
```text
|
||||
signature = hex_lower(HMAC_SHA256(app_secret, string_to_sign))
|
||||
```
|
||||
|
||||
时间窗与防重放：
|
||||
|
||||
- `X-Timestamp` 默认有效时间窗是 300 秒
|
||||
- `X-Nonce` 在有效时间窗内不能重复使用
|
||||
|
||||
## 推荐接入：预签名三段式
|
||||
|
||||
### 1. 初始化上传
|
||||
|
||||
请求：
|
||||
|
||||
```bash
|
||||
curl -X POST 'https://tapi.hifast.biz/v1/public/file/upload/init' \
|
||||
-H 'Accept: application/json, text/plain, */*' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'authorization: your-token' \
|
||||
-H 'X-App-Id: ios-client' \
|
||||
-H 'X-Timestamp: 1778776400' \
|
||||
-H 'X-Nonce: nonce-001' \
|
||||
-H 'X-Signature: your-signature' \
|
||||
-d '{
|
||||
"biz_type": "app-package",
|
||||
"file_name": "demo.zip",
|
||||
"content_type": "application/zip",
|
||||
"size": 123456,
|
||||
"sha256": ""
|
||||
}'
|
||||
```
|
||||
|
||||
典型返回：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"file_id": "c29274ee26ab5aa211e0396e",
|
||||
"object_key": "app-upload/app-package/519/2026/05/c29274ee26ab5aa211e0396e_demo.zip",
|
||||
"upload_url": "https://bucket.s3.ap-east-1.amazonaws.com/...",
|
||||
"method": "PUT",
|
||||
"headers": {
|
||||
"Content-Type": "application/zip"
|
||||
},
|
||||
"expired_at": 1778776715
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 直传 S3
|
||||
|
||||
这一步是直接上传二进制文件到 S3，不走业务签名中间件。
|
||||
|
||||
```bash
|
||||
curl -X PUT 'https://bucket.s3.ap-east-1.amazonaws.com/...' \
|
||||
-H 'Content-Type: application/zip' \
|
||||
--upload-file '/tmp/demo.zip'
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `Content-Type` 需和 `init` 返回的 `headers.Content-Type` 一致
|
||||
- `upload_url` 有过期时间，通常 300 秒
|
||||
- 成功时 S3 常见返回 `200` 或 `204`
|
||||
|
||||
### 3. 完成上传
|
||||
|
||||
```bash
|
||||
curl -X POST 'https://tapi.hifast.biz/v1/public/file/upload/complete' \
|
||||
-H 'Accept: application/json, text/plain, */*' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'authorization: your-token' \
|
||||
-H 'X-App-Id: ios-client' \
|
||||
-H 'X-Timestamp: 1778776405' \
|
||||
-H 'X-Nonce: nonce-002' \
|
||||
-H 'X-Signature: your-signature' \
|
||||
-d '{
|
||||
"file_id": "c29274ee26ab5aa211e0396e"
|
||||
}'
|
||||
```
|
||||
|
||||
## 兼容接入：单接口 multipart 直传
|
||||
|
||||
接口：
|
||||
|
||||
- `POST /v1/public/file/upload`
|
||||
|
||||
表单字段：
|
||||
|
||||
- `biz_type`
|
||||
- `file`
|
||||
|
||||
说明：
|
||||
|
||||
- 该接口继续保留，兼容旧客户端
|
||||
- 如果请求带了 `X-App-Id`，就按现有逻辑验签
|
||||
- 如果没有 `X-App-Id`，仍按旧逻辑放行
|
||||
- 如果要给该接口加签，签名时必须对原始 multipart body 计算 `BODY_SHA256`
|
||||
|
||||
## 常见错误码
|
||||
|
||||
- `200`: 成功
|
||||
- `400`: 参数错误
|
||||
- `40008`: 缺少签名头
|
||||
- `40009`: 签名已过期
|
||||
- `40010`: 签名无效
|
||||
- `40011`: nonce 重放
|
||||
- `10001`: 上传元数据不存在或对象不存在
|
||||
|
||||
## 排查建议
|
||||
|
||||
- `40008`：确认带了 `X-App-Id` 后，也同时带上 `X-Timestamp / X-Nonce / X-Signature`
|
||||
- `40009`：检查客户端时间是否偏差过大
|
||||
- `40010`：确认 `PATH`、query 排序、body 原始字节、secret 是否完全一致
|
||||
- `40011`：确保每次请求都生成新的 `X-Nonce`
|
||||
- `complete` 失败：确认 S3 `PUT` 已成功，且上传大小与 `init.size` 一致
|
||||
@@ -0,0 +1,43 @@
|
||||
package file
|
||||
|
||||
import (
|
||||
"mime/multipart"
|
||||
|
||||
"github.com/gin-gonic/gin"
|
||||
"github.com/perfect-panel/server/internal/logic/public/file"
|
||||
"github.com/perfect-panel/server/internal/svc"
|
||||
"github.com/perfect-panel/server/internal/types"
|
||||
"github.com/perfect-panel/server/pkg/result"
|
||||
)
|
||||
|
||||
// Upload file to RustFS
|
||||
func FileUploadHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
|
||||
return func(c *gin.Context) {
|
||||
var req types.FileUploadRequest
|
||||
_ = c.ShouldBind(&req)
|
||||
validateErr := svcCtx.Validate(&req)
|
||||
if validateErr != nil {
|
||||
result.ParamErrorResult(c, validateErr)
|
||||
return
|
||||
}
|
||||
|
||||
fileHeader, err := c.FormFile("file")
|
||||
if err != nil {
|
||||
result.ParamErrorResult(c, err)
|
||||
return
|
||||
}
|
||||
|
||||
fileReader, err := fileHeader.Open()
|
||||
if err != nil {
|
||||
result.HttpResult(c, nil, err)
|
||||
return
|
||||
}
|
||||
defer func(file multipart.File) {
|
||||
_ = file.Close()
|
||||
}(fileReader)
|
||||
|
||||
l := file.NewFileUploadLogic(c.Request.Context(), svcCtx)
|
||||
resp, err := l.FileUpload(&req, fileHeader, fileReader)
|
||||
result.HttpResult(c, resp, err)
|
||||
}
|
||||
}
|
||||
@@ -870,6 +870,9 @@ func RegisterHandlers(router *gin.Engine, serverCtx *svc.ServiceContext) {
|
||||
publicFileGroupRouter.Use(middleware.AuthMiddleware(serverCtx), middleware.DeviceMiddleware(serverCtx))
|
||||
|
||||
{
|
||||
// Upload file to RustFS
|
||||
publicFileGroupRouter.POST("/upload", publicFile.FileUploadHandler(serverCtx))
|
||||
|
||||
// Init file upload
|
||||
publicFileGroupRouter.POST("/upload/init", publicFile.FileUploadInitHandler(serverCtx))
|
||||
|
||||
|
||||
@@ -0,0 +1,88 @@
|
||||
package file
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"context"
|
||||
"io"
|
||||
"mime/multipart"
|
||||
"net/http"
|
||||
"time"
|
||||
|
||||
"github.com/perfect-panel/server/internal/svc"
|
||||
"github.com/perfect-panel/server/internal/types"
|
||||
"github.com/perfect-panel/server/pkg/logger"
|
||||
"github.com/perfect-panel/server/pkg/xerr"
|
||||
"github.com/pkg/errors"
|
||||
)
|
||||
|
||||
type FileUploadLogic struct {
|
||||
logger.Logger
|
||||
ctx context.Context
|
||||
svcCtx *svc.ServiceContext
|
||||
}
|
||||
|
||||
// Upload file to RustFS
|
||||
func NewFileUploadLogic(ctx context.Context, svcCtx *svc.ServiceContext) *FileUploadLogic {
|
||||
return &FileUploadLogic{
|
||||
Logger: logger.WithContext(ctx),
|
||||
ctx: ctx,
|
||||
svcCtx: svcCtx,
|
||||
}
|
||||
}
|
||||
|
||||
func (l *FileUploadLogic) FileUpload(req *types.FileUploadRequest, fileHeader *multipart.FileHeader, file multipart.File) (resp *types.FileUploadResponse, err error) {
|
||||
u, err := currentUserFromContext(l.ctx)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
if fileHeader == nil {
|
||||
return nil, errors.Wrapf(xerr.NewErrCode(xerr.InvalidParams), "file is required")
|
||||
}
|
||||
|
||||
contentType, err := sniffContentType(fileHeader, file)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if err := validateInitRequest(l.svcCtx, req.BizType, fileHeader.Filename, contentType, fileHeader.Size); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
now := time.Now()
|
||||
fileID := buildFileID(u.Id, req.BizType, fileHeader.Filename)
|
||||
objectKey := buildObjectKey(l.svcCtx.Config.S3.Prefix, u.Id, req.BizType, fileID, fileHeader.Filename, now)
|
||||
|
||||
putResult, err := l.svcCtx.S3Store.PutObject(l.ctx, objectKey, file, fileHeader.Size, contentType)
|
||||
if err != nil {
|
||||
l.Errorw("put object failed", logger.Field("error", err.Error()), logger.Field("user_id", u.Id), logger.Field("file_id", fileID))
|
||||
return nil, err
|
||||
}
|
||||
|
||||
return &types.FileUploadResponse{
|
||||
FileId: fileID,
|
||||
FileName: fileHeader.Filename,
|
||||
ObjectKey: objectKey,
|
||||
Size: fileHeader.Size,
|
||||
ContentType: contentType,
|
||||
Etag: putResult.ETag,
|
||||
Status: fileUploadCompleteStatus,
|
||||
}, nil
|
||||
}
|
||||
|
||||
func sniffContentType(fileHeader *multipart.FileHeader, file multipart.File) (string, error) {
|
||||
if headerType := fileHeader.Header.Get("Content-Type"); headerType != "" {
|
||||
return headerType, nil
|
||||
}
|
||||
if seeker, ok := file.(io.ReadSeeker); ok {
|
||||
buf := make([]byte, 512)
|
||||
n, readErr := seeker.Read(buf)
|
||||
if readErr != nil && readErr != io.EOF {
|
||||
return "", readErr
|
||||
}
|
||||
if _, err := seeker.Seek(0, io.SeekStart); err != nil {
|
||||
return "", err
|
||||
}
|
||||
return http.DetectContentType(bytes.TrimRight(buf[:n], "\x00")), nil
|
||||
}
|
||||
return "application/octet-stream", nil
|
||||
}
|
||||
@@ -762,6 +762,20 @@ type FamilySummary struct {
|
||||
UpdatedAt int64 `json:"updated_at"`
|
||||
}
|
||||
|
||||
type FileUploadRequest struct {
|
||||
BizType string `form:"biz_type" validate:"required"`
|
||||
}
|
||||
|
||||
type FileUploadResponse struct {
|
||||
FileId string `json:"file_id"`
|
||||
FileName string `json:"file_name"`
|
||||
ObjectKey string `json:"object_key"`
|
||||
Size int64 `json:"size"`
|
||||
ContentType string `json:"content_type"`
|
||||
Etag string `json:"etag"`
|
||||
Status string `json:"status"`
|
||||
}
|
||||
|
||||
type FileUploadCompleteRequest struct {
|
||||
FileId string `json:"file_id" validate:"required"`
|
||||
}
|
||||
|
||||
+21
-2
@@ -3,6 +3,7 @@ package storage
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"io"
|
||||
"net/url"
|
||||
"strings"
|
||||
"time"
|
||||
@@ -22,11 +23,15 @@ type PresignUploadResult struct {
|
||||
}
|
||||
|
||||
type ObjectMeta struct {
|
||||
ETag string
|
||||
ContentType string
|
||||
ETag string
|
||||
ContentType string
|
||||
ContentLength int64
|
||||
}
|
||||
|
||||
type PutObjectResult struct {
|
||||
ETag string
|
||||
}
|
||||
|
||||
type S3Store struct {
|
||||
cfg config.S3Config
|
||||
client *s3.Client
|
||||
@@ -96,6 +101,20 @@ func (s *S3Store) HeadObject(ctx context.Context, objectKey string) (*ObjectMeta
|
||||
}, nil
|
||||
}
|
||||
|
||||
func (s *S3Store) PutObject(ctx context.Context, objectKey string, body io.Reader, size int64, contentType string) (*PutObjectResult, error) {
|
||||
resp, err := s.client.PutObject(ctx, &s3.PutObjectInput{
|
||||
Bucket: aws.String(s.cfg.Bucket),
|
||||
Key: aws.String(objectKey),
|
||||
Body: body,
|
||||
ContentLength: aws.Int64(size),
|
||||
ContentType: aws.String(contentType),
|
||||
})
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return &PutObjectResult{ETag: strings.Trim(aws.ToString(resp.ETag), "\"")}, nil
|
||||
}
|
||||
|
||||
func (s *S3Store) BuildObjectURL(objectKey string) string {
|
||||
if s.cfg.PublicBaseURL != "" {
|
||||
return strings.TrimRight(s.cfg.PublicBaseURL, "/") + "/" + strings.TrimLeft(objectKey, "/")
|
||||
|
||||
@@ -0,0 +1,44 @@
|
||||
导出数据库:
|
||||
mysqldump --socket=/var/run/mysqld/mysqld.sock -uroot -p --single-transaction --routines --triggers --events --set-gtid-purged=OFF --source-data=2 --no-tablespaces hifast > /root/data/hifast-final-0515.sql
|
||||
|
||||
jpcV41ppanel
|
||||
|
||||
gzip -1 /root/hifast-final-0515.sql
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
导出redis：
|
||||
redis-cli -a '0BVz9XOHf7KUfEuoFJRK-dURdKUGFiZ8QeaHpysHnKeKhLskZb55HPK121lFsKtr' BGSAVE
|
||||
sleep 5
|
||||
cp /var/lib/redis/dump.rdb /root/data/redis-backup-0515.rdb
|
||||
|
||||
|
||||
导入数据库:
|
||||
gunzip -c /root/hifast-final-0515.sql.gz | docker exec -i ppanel-mysql mysql -uroot -p'jpcV41ppanel' hifast
|
||||
|
||||
|
||||
导入redis：
|
||||
docker stop ppanel-redis
|
||||
docker cp /root/data/redis-backup-0515.rdb ppanel-redis:/data/dump.rdb
|
||||
docker start ppanel-redis
|
||||
docker exec ppanel-redis redis-cli -a 'hifast67yj' DBSIZE
|
||||
|
||||
|
||||
|
||||
docker stop ppanel-redis || true
|
||||
docker rm -f ppanel-redis
|
||||
|
||||
rm -f /root/data/dump.rdb
|
||||
rm -rf /root/data/appendonlydir
|
||||
rm -f /root/data/appendonly.aof*
|
||||
mkdir -p /root/data
|
||||
|
||||
docker pull redis:8.6.3
|
||||
docker run -d \
|
||||
--name ppanel-redis \
|
||||
--restart always \
|
||||
-p 6379:6379 \
|
||||
redis:8.6.3 \
|
||||
redis-server --requirepass 'hifast67yj'
|
||||
Reference in New Issue
Block a user