feat: Initial v0.9 release with API Key authentication
## v0.9.20260325_144654 ### Features - API Key Authentication System - Job Worker System - V2 Backup Versioning ### Bug Fixes - get_processor_results_by_job column mapping Co-authored-by: OpenCode
This commit is contained in:
accusys
504
docs/SFTPGO_DEMO_USER.md
Normal file
504
docs/SFTPGO_DEMO_USER.md
Normal file
@@ -0,0 +1,504 @@
|
||||
# SFTPGo Demo 用戶指南
|
||||
|
||||
## Web 管理介面
|
||||
|
||||
**URL**: https://sftpgo.momentry.ddns.net
|
||||
|
||||
### 登入方式
|
||||
|
||||
| 角色 | 用戶名 | 密碼 |
|
||||
|------|--------|------|
|
||||
| **Demo 用戶** | `demo` | `demopassword123` |
|
||||
|
||||
### 可用功能
|
||||
|
||||
- 瀏覽個人目錄結構
|
||||
- 上傳、下載檔案
|
||||
- 查看上傳記錄
|
||||
|
||||
---
|
||||
|
||||
## 快速連線資訊
|
||||
|
||||
| 項目 | 值 |
|
||||
|------|-----|
|
||||
| **主機** | `momentry.ddns.net` |
|
||||
| **SFTP 連接埠** | `2022` |
|
||||
| **用戶名** | `demo` |
|
||||
| **密碼** | `demopassword123` |
|
||||
| **主目錄** | `/demo` |
|
||||
|
||||
---
|
||||
|
||||
## 連線方式
|
||||
|
||||
### 1. 命令列 SFTP
|
||||
|
||||
```bash
|
||||
# 使用密碼連線
|
||||
sshpass -p "demopassword123" sftp -P 2022 demo@momentry.ddns.net
|
||||
|
||||
# 使用金鑰連線 (需先設定)
|
||||
sftp -P 2022 -i ~/.ssh/id_rsa demo@momentry.ddns.net
|
||||
```
|
||||
|
||||
### 2. FileZilla
|
||||
|
||||
1. **主機**: `sftp://momentry.ddns.net`
|
||||
2. **連接埠**: `2022`
|
||||
3. **協定**: `SFTP`
|
||||
4. **登入類型**: `一般`
|
||||
5. **用戶名**: `demo`
|
||||
6. **密碼**: `demopassword123`
|
||||
|
||||
### 3. Cyberduck (macOS)
|
||||
|
||||
1. 選擇 **連線 > 新連線**
|
||||
2. 協定選擇 **SFTP (SSH File Transfer Protocol)**
|
||||
3. 伺服器: `momentry.ddns.net`
|
||||
4. 連接埠: `2022`
|
||||
5. 使用者名稱: `demo`
|
||||
6. 密碼: `demopassword123`
|
||||
|
||||
### 4. curl 上傳
|
||||
|
||||
```bash
|
||||
curl -u demo:demopassword123 \
|
||||
-T /path/to/video.mp4 \
|
||||
sftp://momentry.ddns.net:2022/demo/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## SFTP 基本操作
|
||||
|
||||
### 連線後常用指令
|
||||
|
||||
```bash
|
||||
# 進入互動式模式
|
||||
sftp demo@momentry.ddns.net -P 2022
|
||||
|
||||
# 常用指令
|
||||
sftp> pwd # 顯示目前目錄
|
||||
sftp> ls # 列出檔案
|
||||
sftp> ls -la # 詳細列表
|
||||
sftp> cd uploads # 切換目錄
|
||||
sftp> mkdir videos # 建立目錄
|
||||
sftp> put local.mp4 # 上傳檔案
|
||||
sftp> get remote.mp4 # 下載檔案
|
||||
sftp> rm old.mp4 # 刪除檔案
|
||||
sftp> exit # 斷線
|
||||
```
|
||||
|
||||
### 批次上傳
|
||||
|
||||
```bash
|
||||
# 上傳多個檔案
|
||||
sshpass -p "demopassword123" sftp -P 2022 demo@momentry.ddns.net <<EOF
|
||||
cd uploads
|
||||
put video1.mp4
|
||||
put video2.mp4
|
||||
put video3.mp4
|
||||
bye
|
||||
EOF
|
||||
|
||||
# 使用 glob 上傳
|
||||
sshpass -p "demopassword123" sftp -P 2022 demo@momentry.ddns.net <<EOF
|
||||
mput /path/to/videos/*.mp4
|
||||
bye
|
||||
EOF
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 自動上傳腳本
|
||||
|
||||
### Bash 腳本
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# upload.sh - 上傳視頻到 Momentry
|
||||
|
||||
HOST="momentry.ddns.net"
|
||||
PORT="2022"
|
||||
USER="demo"
|
||||
PASS="demopassword123"
|
||||
REMOTE_DIR="/demo/uploads"
|
||||
|
||||
# 要上傳的檔案
|
||||
FILE="$1"
|
||||
|
||||
if [ -z "$FILE" ]; then
|
||||
echo "用法: $0 <檔案路徑>"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
sshpass -p "$PASS" sftp -P $PORT $USER@$HOST <<EOF
|
||||
mkdir $REMOTE_DIR
|
||||
cd $REMOTE_DIR
|
||||
put "$FILE"
|
||||
bye
|
||||
EOF
|
||||
|
||||
echo "上傳完成: $FILE"
|
||||
```
|
||||
|
||||
使用方式:
|
||||
```bash
|
||||
chmod +x upload.sh
|
||||
./upload.sh /path/to/video.mp4
|
||||
```
|
||||
|
||||
### Python 腳本
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""上傳檔案到 Momentry SFTP"""
|
||||
|
||||
import paramiko
|
||||
import sys
|
||||
import os
|
||||
|
||||
def upload_file(local_path, remote_dir="/demo/uploads"):
|
||||
host = "momentry.ddns.net"
|
||||
port = 2022
|
||||
username = "demo"
|
||||
password = "demopassword123"
|
||||
|
||||
transport = paramiko.Transport((host, port))
|
||||
transport.connect(username=username, password=password)
|
||||
sftp = paramiko.SFTPClient.from_transport(transport)
|
||||
|
||||
filename = os.path.basename(local_path)
|
||||
remote_path = f"{remote_dir}/{filename}"
|
||||
|
||||
sftp.put(local_path, remote_path)
|
||||
print(f"已上傳: {filename} -> {remote_path}")
|
||||
|
||||
sftp.close()
|
||||
transport.close()
|
||||
|
||||
if __name__ == "__main__":
|
||||
if len(sys.argv) < 2:
|
||||
print("用法: python upload_sftp.py <檔案路徑>")
|
||||
sys.exit(1)
|
||||
|
||||
upload_file(sys.argv[1])
|
||||
```
|
||||
|
||||
安裝依賴:
|
||||
```bash
|
||||
pip install paramiko
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## WebDAV 替代方案
|
||||
|
||||
如果 SFTP 連線有問題，可使用 WebDAV:
|
||||
|
||||
| 項目 | 值 |
|
||||
|------|-----|
|
||||
| **URL** | `https://momentry.ddns.net/webdav/` |
|
||||
| **用戶名** | `demo` |
|
||||
| **密碼** | `demopassword123` |
|
||||
|
||||
### curl 使用 WebDAV
|
||||
|
||||
```bash
|
||||
# 上傳
|
||||
curl -u demo:demopassword123 \
|
||||
-T video.mp4 \
|
||||
"https://momentry.ddns.net/webdav/demo/uploads/"
|
||||
|
||||
# 下載
|
||||
curl -u demo:demopassword123 \
|
||||
-o video.mp4 \
|
||||
"https://momentry.ddns.net/webdav/demo/uploads/video.mp4"
|
||||
|
||||
# 列出目錄
|
||||
curl -u demo:demopassword123 \
|
||||
-X PROPFIND \
|
||||
"https://momentry.ddns.net/webdav/demo/" \
|
||||
-H "Depth: 1"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 連線被拒絕
|
||||
|
||||
```bash
|
||||
# 檢查 SFTPGo 是否運行
|
||||
curl -s http://localhost:8080/api/v2/status | jq .status
|
||||
|
||||
# 檢查連接埠
|
||||
nc -zv momentry.ddns.net 2022
|
||||
```
|
||||
|
||||
### 認證失敗
|
||||
|
||||
確認密碼是否正確:
|
||||
```bash
|
||||
# 測試認證
|
||||
curl -u demo:demopassword123 \
|
||||
"https://momentry.ddns.net/webdav/" -I
|
||||
```
|
||||
|
||||
### 權限不足
|
||||
|
||||
上傳目錄可能需要先建立:
|
||||
```bash
|
||||
sshpass -p "demopassword123" sftp -P 2022 demo@momentry.ddns.net <<EOF
|
||||
mkdir uploads
|
||||
mkdir videos
|
||||
bye
|
||||
EOF
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 檔案上傳後自動化
|
||||
|
||||
上傳後，SFTPGo 會自動:
|
||||
1. 觸發 Hook 腳本
|
||||
2. 記錄上傳事件到 `/Users/accusys/sftpgo_test/hook.log`
|
||||
3. 呼叫 Momentry Core API 註冊視頻
|
||||
|
||||
查看上傳日誌:
|
||||
```bash
|
||||
tail -f /Users/accusys/sftpgo_test/hook.log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 管理手冊
|
||||
|
||||
### 管理員帳戶
|
||||
|
||||
| 角色 | 用戶名 | 密碼 | 說明 |
|
||||
|------|--------|------|------|
|
||||
| **WebAdmin** | `admin` | `Test3200Test3200` | SFTPGo 管理介面 |
|
||||
|
||||
**WebAdmin URL**: https://sftpgo.momentry.ddns.net
|
||||
|
||||
### Admin 創建方式
|
||||
|
||||
根據官方文檔，SFTPGo 有兩種方式創建管理員：
|
||||
|
||||
#### 方式 1: Web UI (首次設定)
|
||||
|
||||
1. 訪問 `http://localhost:8080/web/admin`
|
||||
2. 如果沒有管理員，會顯示設定畫面
|
||||
3. 輸入用戶名和密碼創建第一個管理員
|
||||
|
||||
#### 方式 2: 自動創建 (推薦)
|
||||
|
||||
需要同時滿足以下條件：
|
||||
1. 配置文件中設定 `"create_default_admin": true`
|
||||
2. 設定環境變數 `SFTPGO_DEFAULT_ADMIN_USERNAME` 和 `SFTPGO_DEFAULT_ADMIN_PASSWORD`
|
||||
|
||||
### 設定步驟
|
||||
|
||||
#### Step 1: 確保配置文件正確
|
||||
|
||||
確認 `/Users/accusys/momentry/etc/sftpgo/sftpgo.json` 中有：
|
||||
```json
|
||||
{
|
||||
"data_provider": {
|
||||
"create_default_admin": true
|
||||
},
|
||||
"httpd": {
|
||||
"setup": {
|
||||
"installation_code": "Test3200Test3200"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Step 2: 更新 plist 加入環境變數
|
||||
|
||||
編輯 `/Library/LaunchDaemons/com.momentry.sftpgo.plist`，加入：
|
||||
```xml
|
||||
<key>EnvironmentVariables</key>
|
||||
<dict>
|
||||
<key>SFTPGO_DEFAULT_ADMIN_USERNAME</key>
|
||||
<string>admin</string>
|
||||
<key>SFTPGO_DEFAULT_ADMIN_PASSWORD</key>
|
||||
<string>Test3200Test3200</string>
|
||||
</dict>
|
||||
```
|
||||
|
||||
#### Step 3: 重啟 SFTPGo
|
||||
|
||||
```bash
|
||||
launchctl unload homebrew.mxcl.sftpgo
|
||||
launchctl load homebrew.mxcl.sftpgo
|
||||
```
|
||||
|
||||
#### Step 4: 驗證管理員
|
||||
|
||||
```bash
|
||||
curl -s -X GET "http://localhost:8080/api/v2/token" \
|
||||
-u "admin:Test3200Test3200"
|
||||
```
|
||||
|
||||
成功回應：
|
||||
```json
|
||||
{
|
||||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"token_type": "bearer",
|
||||
"expires_in": 1200
|
||||
}
|
||||
```
|
||||
|
||||
### REST API 認證流程
|
||||
|
||||
#### 1. 獲取 Token
|
||||
|
||||
```bash
|
||||
curl -s -X GET "http://localhost:8080/api/v2/token" \
|
||||
-u "admin:Test3200Test3200"
|
||||
```
|
||||
|
||||
#### 2. 使用 Token 訪問 API
|
||||
|
||||
```bash
|
||||
TOKEN=$(curl -s -X GET "http://localhost:8080/api/v2/token" \
|
||||
-u "admin:Test3200Test3200" | jq -r '.access_token')
|
||||
|
||||
# 查看所有用戶
|
||||
curl -s http://localhost:8080/api/v2/users \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
|
||||
# 查看系統狀態
|
||||
curl -s http://localhost:8080/api/v2/status \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
### 常用管理操作
|
||||
|
||||
#### 查看所有用戶
|
||||
|
||||
```bash
|
||||
TOKEN=$(curl -s -X GET "http://localhost:8080/api/v2/token" \
|
||||
-u "admin:Test3200Test3200" | jq -r '.access_token')
|
||||
|
||||
curl -s http://localhost:8080/api/v2/users \
|
||||
-H "Authorization: Bearer $TOKEN" | jq .
|
||||
```
|
||||
|
||||
#### 建立新用戶
|
||||
|
||||
```bash
|
||||
TOKEN=$(curl -s -X GET "http://localhost:8080/api/v2/token" \
|
||||
-u "admin:Test3200Test3200" | jq -r '.access_token')
|
||||
|
||||
curl -s -X POST http://localhost:8080/api/v2/users \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"username": "newuser",
|
||||
"password": "userpassword123",
|
||||
"email": "user@example.com",
|
||||
"status": 1,
|
||||
"home_dir": "/Users/accusys/momentry/var/sftpgo/data/newuser",
|
||||
"uid": 501,
|
||||
"gid": 20,
|
||||
"permissions": {
|
||||
"/": ["*"]
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
#### 建立用戶組
|
||||
|
||||
```bash
|
||||
TOKEN=$(curl -s -X GET "http://localhost:8080/api/v2/token" \
|
||||
-u "admin:Test3200Test3200" | jq -r '.access_token')
|
||||
|
||||
curl -s -X POST http://localhost:8080/api/v2/groups \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "editors",
|
||||
"description": "Editor group with upload permissions"
|
||||
}'
|
||||
```
|
||||
|
||||
#### 刪除用戶
|
||||
|
||||
```bash
|
||||
TOKEN=$(curl -s -X GET "http://localhost:8080/api/v2/token" \
|
||||
-u "admin:Test3200Test3200" | jq -r '.access_token')
|
||||
|
||||
curl -s -X DELETE http://localhost:8080/api/v2/users/username \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
#### 修改用戶密碼
|
||||
|
||||
```bash
|
||||
TOKEN=$(curl -s -X GET "http://localhost:8080/api/v2/token" \
|
||||
-u "admin:Test3200Test3200" | jq -r '.access_token')
|
||||
|
||||
curl -s -X PUT http://localhost:8080/api/v2/users/demo \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"password": "newpassword456"
|
||||
}'
|
||||
```
|
||||
|
||||
### 重要設定
|
||||
|
||||
| 設定項目 | 值 | 說明 |
|
||||
|----------|-----|------|
|
||||
| **SFTP 連接埠** | `2022` | SSH 檔案傳輸協定 |
|
||||
| **HTTP/WebDAV 連接埠** | `8080` | 內部 HTTP 服務 |
|
||||
| **WebAdmin 連接埠** | `8080` | 管理介面 (`/web/admin`) |
|
||||
| **WebClient 連接埠** | `8080` | 用戶介面 (`/web/client`) |
|
||||
| **資料庫** | PostgreSQL | 用戶和設定儲存 |
|
||||
| **Hook 腳本** | `/Users/accusys/sftpgo_test/register_hook.sh` | 上傳後自動化處理 |
|
||||
| **安裝碼** | `Test3200Test3200` | 首次設定管理員所需 |
|
||||
| **create_default_admin** | `true` | 自動創建管理員 |
|
||||
| **Token 有效期** | 1200 秒 (20分鐘) | JWT 過期時間 |
|
||||
|
||||
### 用戶目錄結構
|
||||
|
||||
所有 SFTPGo 用戶資料統一存放在 `/Users/accusys/momentry/var/sftpgo/data/` 目錄下：
|
||||
|
||||
| 用戶 | 資料夾路徑 | 密碼 | 說明 |
|
||||
|------|------------|------|------|
|
||||
| **demo** | `/Users/accusys/momentry/var/sftpgo/data/demo` | `demopassword123` | Demo 用戶上傳目錄 |
|
||||
| **momentry** | `/Users/accusys/momentry/var/sftpgo/data/momentry` | `momentry123` | Momentry 系統用戶 |
|
||||
| **warren** | `/Users/accusys/momentry/var/sftpgo/data/warren` | `warren123` | 其他用戶 |
|
||||
|
||||
### API Token 獲取方式
|
||||
|
||||
```bash
|
||||
# 注意：使用 GET 而非 POST
|
||||
curl -s -X GET "http://localhost:8080/api/v2/token" \
|
||||
-u "admin:Test3200Test3200" | jq .access_token
|
||||
```
|
||||
|
||||
### 故障排除
|
||||
|
||||
| 問題 | 解決方案 |
|
||||
|------|----------|
|
||||
| 無法獲取 Token | 確認環境變數已正確設定並重啟 SFTPGo |
|
||||
| SFTP 連線被拒絕 | 檢查 SFTPGo 服務: `launchctl list \| grep sftpgo` |
|
||||
| 無法登入 WebAdmin | 確認 admin 用戶存在: 檢查 plist 中環境變數是否正確 |
|
||||
| 上傳失敗 | 檢查 Hook 腳本: `tail -f /Users/accusys/momentry/log/sftpgo.error.log` |
|
||||
| 權限不足 | 檢查用戶權限或更新 `permissions` 設定 |
|
||||
| API 返回 401 | Token 過期，需重新獲取: `curl -X POST .../token -u "admin:pass"` | |
|
||||
|
||||
---
|
||||
|
||||
## 安全注意事項
|
||||
|
||||
- **密碼保護**: `demopassword123` 為 demo 帳戶密碼
|
||||
- **限制存取**: Demo 用戶只能訪問 `/demo` 目錄
|
||||
- **監控**: 所有上傳都有日誌記錄
|
||||
- **生產環境**: 正式環境應使用更強的密碼和金鑰認證
|
||||
Reference in New Issue
Block a user