# 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` 目錄
- **監控**: 所有上傳都有日誌記錄
- **生產環境**: 正式環境應使用更強的密碼和金鑰認證