# 跨服务器文件传输

## 日期

2026-06-21

## 摘要

文件管理器新增 A→B 跨机传输：**直传**（中心 SFTP 中继，单文件 ≤500MB）与 **打包投递**（源机 tar.gz → 签名下载 URL → 目标机 curl + 可选解压，一键完成）。

## 动机

同机剪贴板无法跨服务器；运维需对标宝塔「发送到服务器 / 打包下载」能力，避免本地下载再上传。

## 涉及文件

- `server/application/services/server_file_transfer_service.py` — 直传、打包、投递编排
- `server/infrastructure/redis/transfer_package_store.py` — 下载 token 元数据
- `server/api/sync_v2.py` — `server-transfer`、`server-transfer/deliver`、`transfer-download`
- `server/api/schemas.py` — 请求模型
- `server/api/auth_jwt.py` — 下载端点 JWT 豁免
- `frontend/src/composables/files/useFilesActions.ts` — 对话框与 API 调用
- `frontend/src/components/files/FilesDialogs.vue`、`FilesToolbar.vue`、`FilesList.vue`
- `frontend/src/utils/auditLabels.ts`
- `tests/test_server_file_transfer.py`
- `docs/design/specs/2026-06-21-server-file-transfer-design.md`

## 迁移 / 重启

- 需重启 API（新路由 + Redis key `transfer:pkg:*`）
- 无需 DB 迁移
- 前端需 `vite build` 后部署 `web/app/`

## 验证

```bash
pytest tests/test_server_file_transfer.py -q
cd frontend && npm run type-check
bash scripts/local_verify.sh
```

- 文件页选中项 →「发送到其他服务器」→ 直传 / 打包投递
- `GET /api/sync/transfer-download/{token}` 无 JWT 可 curl；过期 404
- 审计动作：`server_file_relay`、`server_file_deliver`