基於 Swoole 實現高效安全 FTP 服務器（二）：核心類架構詳解

系列文章導讀

本文為「使用 PHP 實現高效安全 FTP 服務器」系列第二部分，重點剖析四大核心類的設計與實現：User（用戶/權限管理）、ShareMemory（共享內存）、CWebServer（內嵌 HTTP 管理後台）、CFtpServer（FTP 主邏輯）。第一部分請參考《基於 Swoole 實現高效安全 FTP 服務器（一）：協議與架構設計》。

一、用戶與權限管理類 User

1.1 數據存儲結構

採用 JSON 文件存儲，分離用戶表（users）與組表（groups），支援多層級權限繼承。

// 用戶記錄結構
[
  'user1' => [
    'pass'       => 'md5_hash',           // 密碼鹽值哈希
    'group'      => 'group1',             // 所屬組
    'home'       => '/home/ftp/',         // FTP 根目錄
    'active'     => true,                 // 啟用狀態
    'expired'    => '2025-12-31',         // 過期時間
    'description'=> '',                   // 備註
    'email'      => 'user@example.com',   // 郵箱
    'folder'     => [                     // 目錄精細權限
      ['path' => '/home/ftp/',  'access' => 'RWANDLCNDI'],
      ['path' => '/home/ftp/a/', 'access' => 'RWAND-----']
    ],
    'ip' => [                             // IP 白/黑名單
      'allow' => ['192.168.1.*'],
      'deny'  => ['10.0.0.5']
    ]
  ]
]

// 組記錄結構
[
  'group1' => [
    'home'   => '/home/ftp/dept1/',
    'folder' => [...],  // 同用戶 folder 結構
    'ip'     => [...]
  ]
]

1.2 權限位定義（10 位字符串）

權限字符串示例：RWANDLCNDI 表示擁有所有權限；RWAND----- 僅擁有文件權限，無目錄操作權限。

1.3 核心方法速覽

• addUser() / setUserProfile() / delUser()：用戶增刪改
• addGroup() / setGroupProfile() / delGroup()：組管理
• checkUser($user, $pass, $ip)：綜合驗證（密碼、過期、IP 白黑名單）
• getPathAccess($user, $path)：最長路徑匹配獲取權限，支援繼承邏輯
• isReadable()/isWritable()/isFolderListable()...：具體權限判斷快捷方法
• addOnline() / addAttempt() / isAttemptLimit()：基於共享內存的在線用戶統計與暴力破解防護

二、共享內存操作類 ShareMemory

封裝 shmop 擴展，提供進程間數據共享（在線用戶、Pasv 端口佔用、登錄失敗記錄）。

class ShareMemory {
    private $mode = 0644;
    private $shm_key;
    private $shm_size = 1048577; // 1MB + 1 byte 結束符

    public function __construct() {
        $this->shm_key = ftok(__FILE__, 'F');
    }

    public function read() { /* 讀取並 json_decode */ }
    public function write(array $arr) { /* json_encode 寫入 */ }
    public function delete() { /* 刪除共享內存塊 */ }
}

關鍵點：以 \0 作為字符串結束標記；寫入前檢查大小不超過分配空間；讀取時自動截斷結束符後內容。

三、內嵌 HTTP 管理後台 CWebServer

基於 Swoole 實現的輕量級 HTTP 服務，專為 FTP 管理介面設計，支援靜態文件、PHP 腳本執行、Basic Auth 驗證、緩存控制。

3.1 請求處理流程

1. onReceive 接收數據 → checkData 判斷請求頭/體完整性
2. parseHeader 解析請求行與 Headers
3. checkPost 處理 POST 體長度驗證（防大包攻擊）
4. parseRequest 填充 $_GET/$_POST/$_COOKIE/$_SERVER 等超全局變量
5. process 路由分發：PHP 文件經 include 執行，靜態文件直接輸出
6. parseResponse 組裝 HTTP 響應頭與體發送

3.2 安全與限制

• 路徑穿越防護：path_deny 禁止訪問 /protected/ 等敏感目錄
• Basic Auth：管理介面僅允許 admin 組用戶訪問
• POST 大小限制：默認 1MB，Header 限制 8KB
• 靜態文件緩存：30 天 Cache-Control，支援 If-Modified-Since 304 響應

四、FTP 主服務類 CFtpServer

繼承 Swoole 事件驅動模型，整合上述組件，實現完整 FTP 協議邏輯（RFC 959/2228/2389/3659）。

4.1 服務啟動與管理

// 啟動腳本入口
CFtpServer::setPidFile('/var/run/ftp_server.pid');
CFtpServer::start(function() {
    $server = new CFtpServer('0.0.0.0', 21);
    $server->daemonize(); // 守護進程模式
    $server->run([
        'worker_num'       => 4,
        'max_connection'   => 500,
        'manager_port'     => 8080,   // HTTP 管理端口
        'ftps_port'        => 990,    // FTPS 隱式 SSL 端口
        'passive_port_range' => [55000, 60000],
        'ssl_cert_file'    => '/etc/ssl/ftp_server.pem',
        'ssl_key_file'     => '/etc/ssl/ftp_server.key',
        'force_ssl'        => false,  // 強制 FTPS
        'log_file'         => '/var/log/ftp_server.log',
        'pid_file'         => '/var/run/ftp_server.pid',
    ]);
});

4.2 核心協議命令實現

4.3 被動模式與 SSL 數據連接

• getPasvPort()：從配置範圍隨機選取可用端口，併發安全
• pushPasvPort()/popPasvPort()：共享內存記錄端口佔用，避免衝突
• SSL 數據連接：stream_socket_server('ssl://...') 配合 stream_context_create 載入證書

4.4 管理控制台指令（CONSOLE）

僅 admin 組用戶可用，格式：COMMAND||JSON_PARAMS

USER-ADD||{"user":"test","pass":"123456","home":"/home/ftp/","expired":"2025-12-31","active":true,"group":"users"}
GROUP-SET-PROFILE||{"group":"users","profile":{"folder":[{"path":"/home/ftp/data/","access":"RWANDLCNDI"}]}}
DISK-FREE||{"path":"/home/ftp"}

五、部署與運維建議

1. 防火牆：放行 21（控制）、990（FTPS）、55000-60000（Pasv 範圍）；啟用 SSL 時需配置 NAT 穿透。
2. 日誌輪轉：代碼內建 200MB 分割，建議配合 logrotate 定期清理。
3. 進程管理：使用 php server.php start|stop|reload 控制；reload 發送 SIGUSR1 平滑重啟 Worker。
4. 擴展依賴：swoole >= 1.7.20、posix、shmop、openssl。

總結

本文詳細拆解了基於 Swoole 的 FTP 服務器四大核心類，涵蓋用戶權限體系、共享內存協作、內嵌 HTTP 管理、完整協議實現。該架構具備高併發、精細權限、FTPS 加密、Web 管理等企業級特性，可作為生產環境文件傳輸服務的基礎框架。後續可擴展：分佈式存儲適配、WebDAV 支援、審計日誌對接 SIEM 等。