da856d89ff
- Create README.md for internationalization (i18n) documentation - Add English translation for main README and quick start guide - Add Japanese translation for main README - Add Simplified Chinese translation for main README - Introduce sample Docker Compose configurations for various deployment scenarios - Implement CI/CD documentation for testing and deployment workflows - Establish end-to-end testing guidelines and strategies - Create test strategy documentation outlining unit, integration, and E2E tests
193 lines
3.6 KiB
Markdown
193 lines
3.6 KiB
Markdown
# URL ID 與儲存機制
|
||
|
||
> ⚠️ **此文件已遷移**
|
||
>
|
||
> 本文件內容已整合至新的文件結構，請參閱：
|
||
>
|
||
> - 🛠️ [專案結構](development/project-structure.md)
|
||
> - 🐳 [Docker 部署](deployment/docker.md)
|
||
>
|
||
> 此文件將在未來版本中移除。
|
||
|
||
---
|
||
|
||
## 檔案儲存結構
|
||
|
||
ConvertX-CN 使用以下目錄結構儲存檔案：
|
||
|
||
```
|
||
/app/data/
|
||
├── convertx.db # SQLite 資料庫
|
||
├── uploads/ # 上傳的原始檔案
|
||
│ └── {user_id}/
|
||
│ └── {job_id}/
|
||
│ ├── file1.docx
|
||
│ └── file2.pdf
|
||
└── output/ # 轉換後的檔案
|
||
└── {user_id}/
|
||
└── {job_id}/
|
||
├── file1.pdf
|
||
└── file2.txt
|
||
```
|
||
|
||
---
|
||
|
||
## Job ID 說明
|
||
|
||
每次轉換任務都會產生一個唯一的 Job ID，用於：
|
||
|
||
- 追蹤轉換進度
|
||
- 組織檔案儲存
|
||
- 生成下載連結
|
||
|
||
### Job ID 格式
|
||
|
||
Job ID 是一個 UUID v4 格式的字串，例如：
|
||
|
||
```
|
||
550e8400-e29b-41d4-a716-446655440000
|
||
```
|
||
|
||
---
|
||
|
||
## URL 結構
|
||
|
||
### 結果頁面
|
||
|
||
```
|
||
/results/{job_id}
|
||
```
|
||
|
||
例如：
|
||
|
||
```
|
||
http://localhost:3000/results/550e8400-e29b-41d4-a716-446655440000
|
||
```
|
||
|
||
### 下載單一檔案
|
||
|
||
```
|
||
/download/{user_id}/{job_id}/{filename}
|
||
```
|
||
|
||
### 下載所有檔案（Tar）
|
||
|
||
```
|
||
/archive/{job_id}
|
||
```
|
||
|
||
---
|
||
|
||
## 資料持久化
|
||
|
||
### Docker Volume 映射
|
||
|
||
為了確保資料不會在容器重啟後遺失，請務必映射 `/app/data` 目錄：
|
||
|
||
```yaml
|
||
volumes:
|
||
- ./data:/app/data
|
||
```
|
||
|
||
或使用 Named Volume：
|
||
|
||
```yaml
|
||
volumes:
|
||
- convertx-data:/app/data
|
||
|
||
volumes:
|
||
convertx-data:
|
||
```
|
||
|
||
---
|
||
|
||
## 自動清理
|
||
|
||
ConvertX-CN 會根據 `AUTO_DELETE_EVERY_N_HOURS` 設定自動清理過期檔案。
|
||
|
||
### 清理邏輯
|
||
|
||
1. 系統每 N 小時執行一次清理
|
||
2. 刪除建立時間超過 N 小時的 Job
|
||
3. 同時刪除對應的上傳檔案和輸出檔案
|
||
4. 資料庫記錄也會被清除
|
||
|
||
### 設定範例
|
||
|
||
```yaml
|
||
# 每 24 小時清理一次
|
||
- AUTO_DELETE_EVERY_N_HOURS=24
|
||
|
||
# 每 1 小時清理一次（公開服務建議）
|
||
- AUTO_DELETE_EVERY_N_HOURS=1
|
||
|
||
# 停用自動清理
|
||
- AUTO_DELETE_EVERY_N_HOURS=0
|
||
```
|
||
|
||
---
|
||
|
||
## 資料庫
|
||
|
||
ConvertX-CN 使用 SQLite 作為資料庫，儲存於 `/app/data/convertx.db`。
|
||
|
||
### 資料表結構
|
||
|
||
#### users
|
||
|
||
| 欄位 | 類型 | 說明 |
|
||
| -------- | ------- | --------- |
|
||
| id | INTEGER | 使用者 ID |
|
||
| email | TEXT | 電子郵件 |
|
||
| password | TEXT | 密碼雜湊 |
|
||
|
||
#### jobs
|
||
|
||
| 欄位 | 類型 | 說明 |
|
||
| ------------ | ------- | --------- |
|
||
| id | TEXT | Job UUID |
|
||
| user_id | INTEGER | 使用者 ID |
|
||
| num_files | INTEGER | 檔案數量 |
|
||
| date_created | TEXT | 建立時間 |
|
||
|
||
#### file_names
|
||
|
||
| 欄位 | 類型 | 說明 |
|
||
| ---------------- | ------- | -------- |
|
||
| id | INTEGER | 檔案 ID |
|
||
| job_id | TEXT | Job UUID |
|
||
| input_file_name | TEXT | 原始檔名 |
|
||
| output_file_name | TEXT | 輸出檔名 |
|
||
| status | TEXT | 轉換狀態 |
|
||
|
||
---
|
||
|
||
## 備份與還原
|
||
|
||
### 備份
|
||
|
||
```bash
|
||
# 備份整個 data 目錄
|
||
tar -czvf convertx-backup-$(date +%Y%m%d).tar.gz ./data
|
||
|
||
# 僅備份資料庫
|
||
cp ./data/convertx.db ./backup-convertx-$(date +%Y%m%d).db
|
||
```
|
||
|
||
### 還原
|
||
|
||
```bash
|
||
# 還原整個 data 目錄
|
||
tar -xzvf convertx-backup-20240101.tar.gz
|
||
|
||
# 還原資料庫
|
||
cp ./backup-convertx-20240101.db ./data/convertx.db
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事項
|
||
|
||
1. **權限問題**：確保 Docker 容器有權限寫入 data 目錄
|
||
2. **磁碟空間**：大量轉換可能佔用大量磁碟空間，建議設定自動清理
|
||
3. **資料安全**：敏感文件轉換後建議手動刪除或縮短保留時間
|