【實戰】SFTPGo 2.7 在 Rocky Linux 8/9 安裝失敗排查：5 分鐘用 CLI 解決常見錯誤 (2026 最新)

作者：

📚 延伸閱讀：相關技術系列

📝 SFTP 伺服器完全指南 SFTPGo 2.7.0 從零到可用的完整攻略

這是一份從乾淨系統到完全可用的實戰紀錄。涵蓋：

  • 系統準備 - Python3、curl、防火牆設定
  • SFTPGo 安裝 - Yum repo + systemd 啟動
  • 目錄規劃 - /var/sftp 架構設計
  • WebAdmin 設定 - 群組、使用者、權限管理
  • 日誌落地 - 輪替、壓縮、容量控制
  • 中文化 - en 繁體覆蓋 + python3 驗證
💡 為什麼選 SFTPGo？ SFTPGo vs 傳統 OpenSSH SFTP

傳統做法是在 Linux 上開啟 OpenSSH SFTP 服務，配合系統帳號管理檔案存取。但這種方式面臨：

  • ❌ 需要為每個使用者建立系統帳號（成本高）
  • ❌ 權限管理分散在系統層、難以維護
  • ❌ 無統一的 Web 介面，管理全靠 SSH 指令
  • ❌ 無法進行細粒度權限控制（誰能看哪個資料夾）
  • ❌ 日誌分散，難以追蹤登入/上下載行為

SFTPGo 優勢：

  • ✅ Web 管理介面 - 無需 SSH 即可管理使用者
  • ✅ 虛擬資料夾 - 靈活配置使用者看得到的路徑
  • ✅ 完整日誌 - JSON 格式記錄所有連線/操作
  • ✅ 自動輪替 - 日誌自動壓縮、封頂容量
  • ✅ 中文化支援 - 開源社群提供繁中翻譯
SFTPGo Logo and Interface SFTPGo 官方介面示意

第一章：系統準備

1.1 檢查系統版本與架構

執行以下指令確認環境：

cat /etc/os-release uname -m
Check System Version

1.2 安裝必要工具

SFTPGo 需要 Python 3 與 curl：

sudo dnf install -y python3 curl python3 --version curl --version
✅ 用途說明
  • Python 3：驗證 JSON 格式（中文化時用 `python3 -m json.tool`）
  • curl：下載官方 Yum repo 檔案
Install Python3 and Curl

1.3 防火牆設定（若有 firewalld）

# 檢查 firewalld 狀態 sudo systemctl is-active firewalld # 若顯示 active，執行以下開放埠 sudo firewall-cmd --permanent --add-port=2022/tcp sudo firewall-cmd --permanent --add-port=8080/tcp sudo firewall-cmd --reload # 驗證規則生效 sudo firewall-cmd --list-ports
Firewall Configuration

第二章：安裝 SFTPGo

2.1 建立官方 Yum repo

ARCH=$(uname -m) curl -sS https://ftp.osuosl.org/pub/sftpgo/yum/${ARCH}/sftpgo.repo | sudo tee /etc/yum.repos.d/sftpgo.repo
Setup Yum Repo

2.2 安裝 SFTPGo 套件

sudo dnf install -y sftpgo
Install SFTPGo Package

2.3 啟動服務

# 啟動 + 開機自啟 sudo systemctl start sftpgo sudo systemctl enable sftpgo # 檢查狀態 sudo systemctl status sftpgo --no-pager
Start SFTPGo Service

2.4 驗證埠監聽

確認 SFTP (2022) 和 WebAdmin (8080) 埠已啟用：

ss -lntp | egrep ':(2022|8080)\b'
Check Ports SFTPGo 服務正常執行，埠已監聽

第三章：目錄規劃與權限設定

3.1 目錄結構設計

推薦以下結構（最佳實踐）：

/var/sftp/ ├── users/ # 使用者家目錄區 │ ├── aaa/ # 使用者 aaa 自動生成 │ ├── bbb/ # 使用者 bbb 自動生成 │ └── ... └── share/ # 全員共用區

3.2 建立目錄結構

sudo mkdir -p /var/sftp/users /var/sftp/share

3.3 設定所有人與權限

SFTPGo 必須是目錄擁有者才能讀寫：

# 設定擁有者為 sftpgo sudo chown -R sftpgo:sftpgo /var/sftp # 設定權限（750 = 擁有者完全、群組讀執行、其他無權限） sudo chmod 0750 /var/sftp sudo chmod 0750 /var/sftp/users # share 目錄設為 770（多人可寫） sudo chmod 0770 /var/sftp/share
✅ 驗證重點
  • owner 和 group 都是 sftpgo
  • /var/sftp 與 /var/sftp/users 為 750
  • /var/sftp/share 為 770（多人寫入）
Directory Permissions 截目錄權限設定完成，所有者為 sftpgo

第四章：WebAdmin 初始設定

4.1 開啟 WebAdmin 介面

用瀏覽器訪問：

http://<主機IP>:8080/web/admin 例如：http://192.168.120.111:8080/web/admin
WebAdmin Login WebAdmin 首次進入，需建立第一個管理員

4.2 建立管理員帳號

首次登入時會自動進入 Setup，填入：

  • Username：admin（或自訂）
  • Password：設定強密碼

點擊 Submit 後會自動登入，2FA 提示可選擇 Skip。

Create Admin
2FA Skip 建立第一個管理員成功 (2FA 可選擇略過或設定)

4.3 建立 Primary 群組（重點）

群組可以統一套用設定給多個使用者，避免逐一手動設定。

步驟：

  1. 點擊左側選單 Groups
  2. 點擊 Add group 按鈕
  3. 填入以下欄位：
欄位 值 說明
Name Primary 群組名稱（必填）
File system Local disk 存儲類型
Storage Local disk 存儲提供者
Root directory /var/sftp/users/%username% 【重點】%username% 會自動替換為帳號
Download buffer 0 保留預設
Upload buffer 0 保留預設

點擊 Submit 儲存群組。

Create Primary Group 建立 Primary 群組，設定 Root directory 為 /var/sftp/users/%username%

4.4 建立測試使用者

步驟：

  1. 點擊左側選單 Users
  2. 點擊 Add user 按鈕
  3. 填入必要欄位：
欄位 值 說明
Username aaa 使用者帳號（測試用，可自訂）
Password 輸入密碼 或用 Public Key（二選一）
Primary group Primary 指定剛建的 Primary 群組

點擊 Submit 建立使用者。

Create Test User 建立測試使用者 aaa

4.5 用 SFTP 測試登入與上傳

在本機或任何可連到主機的 Linux 機器上執行：

sftp -P 2022 aaa@127.0.0.1 # 進入 SFTP 提示符後，試著上傳檔案： > put /path/to/testfile.txt > ls > exit

預期行為：

  • ✅ 第一次登入時，SFTPGo 自動建立 /var/sftp/users/aaa/
  • ✅ 檔案上傳成功
  • ✅ 查看檔案列表正常

4.6 驗證檔案與權限

在伺服器上檢查：

ls -l /var/sftp/users/aaa/
Verify File Upload
Verify Directory Listing 使用者檔案已成功上傳到 /var/sftp/users/aaa/
✅ WebAdmin 基本設定完成
使用者已可透過 SFTP 登入並上傳檔案，目錄自動建立工作正常。

第五章：日誌設定（含輪替）

5.1 建立日誌目錄

sudo mkdir -p /var/log/sftpgo sudo chown -R sftpgo:sftpgo /var/log/sftpgo sudo chmod 0750 /var/log/sftpgo

5.2 建立環境變數檔（日誌參數）

日誌參數透過環境變數控制，SFTPGo 官方推薦此方式：

sudo tee /etc/sftpgo/sftpgo.env >/dev/null <<'EOF' SFTPGO_LOG_FILE_PATH=/var/log/sftpgo/sftpgo.log SFTPGO_LOG_LEVEL=info SFTPGO_LOG_MAX_SIZE=100 SFTPGO_LOG_MAX_BACKUPS=50 SFTPGO_LOG_MAX_AGE=90 SFTPGO_LOG_COMPRESS=true EOF

參數說明：

參數 值 說明
SFTPGO_LOG_FILE_PATH /var/log/sftpgo/sftpgo.log 日誌檔案路徑
SFTPGO_LOG_LEVEL info 日誌等級（debug/info/warn/error）
SFTPGO_LOG_MAX_SIZE 100 單個日誌檔大小上限（MB）
SFTPGO_LOG_MAX_BACKUPS 50 保留最多 50 個備份檔
SFTPGO_LOG_MAX_AGE 90 日誌保留天數
SFTPGO_LOG_COMPRESS true 備份檔自動 gzip 壓縮

5.3 設定 systemd 讀取環境變數

編輯 systemd override 檔案，讓 SFTPGo 載入環境變數：

sudo systemctl edit sftpgo

貼入以下內容（若檔案為空）：

[Service] EnvironmentFile=-/etc/sftpgo/sftpgo.env

存檔後（通常 Ctrl+X → Y → Enter）。

5.4 重新啟動生效

sudo systemctl daemon-reload sudo systemctl restart sftpgo

5.5 驗證日誌有寫入

# 查看日誌檔 ls -l /var/log/sftpgo/ tail -n 20 /var/log/sftpgo/sftpgo.log

預期輸出： JSON 格式的日誌，包含連線/登入/檔案操作等事件。

Log JSON Output 日誌已正常生成，JSON 格式記錄各項事件
💡 日誌內容示例 (JSON 格式)

SFTPGo 的日誌分為「系統訊息」與「操作紀錄」。

▼ 系統啟動日誌 (您目前看到的)：
{"level":"info","time":"2026-02-04T03:46:13.328","sender":"sftpd","message":"server listener registered, address: [::]:2022"}
▼ 使用者操作日誌 (有人登入後會出現)：
{"level":"info","time":"2026-02-04T04:00:00.123","sender":"connection","event_type":"login_success","username":"admin","client_ip":"192.168.1.10",...}

第六章：中文化（繁體設定）

⚠️ 前置條件
必須有「繁體中文的 translation.json 檔案」。若無，請先準備此檔案或用 cat/tee 建立。

6.1 準備繁中翻譯檔

假設你已有繁中 translation.json 放在 /root/translation.json：

# 檢查檔案是否存在 ls -l /root/translation.json # 查看前 20 行，確認是繁中 head -n 20 /root/translation.json

預期輸出： 應看到繁體中文如「初始設定」、「登入」、「檔案」等字。

Check Translation File 繁中 translation.json 檔案內容確認

6.2 驗證 JSON 語法

用 python3 檢查 JSON 是否合法：

python3 -m json.tool /root/translation.json >/dev/null echo $?

預期輸出： 0 表示語法正確；若有錯會直接報錯行列。

6.3 找到 en 翻譯檔位置

find / -path '*/static/locales/en/translation.json' 2>/dev/null

預期輸出： /usr/share/sftpgo/static/locales/en/translation.json

6.4 備份原始 en（英文版）

sudo cp -a /usr/share/sftpgo/static/locales/en/translation.json \ /usr/share/sftpgo/static/locales/en/translation.json.bak

6.5 覆蓋 en 成繁中

sudo cp -a /root/translation.json \ /usr/share/sftpgo/static/locales/en/translation.json

6.6 再驗一次（已套用的 en）

python3 -m json.tool /usr/share/sftpgo/static/locales/en/translation.json >/dev/null echo $?

預期輸出： 0

6.7 重啟 SFTPGo

sudo systemctl restart sftpgo

6.8 備份「已套用的繁中 en」到 /root（含日期）

sudo cp -a /usr/share/sftpgo/static/locales/en/translation.json \ "/root/sftpgo.translation.zh-TW.$(date +%F_%H%M%S).json"

6.9 驗證備份檔

ls -l /root/sftpgo.translation.zh-TW.*.json

6.10 清瀏覽器快取並驗證

  1. 進 WebAdmin：http://<主機IP>:8080/web/admin
  2. 按 F12 開啟開發者工具 → 應用程式 → 本機存儲 → 清除該站台的 localStorage（特別是 i18next* 開頭的項）
  3. 重新整理頁面
  4. 預期：UI 應顯示繁體中文（「登入」、「檔案」、「使用者」等）
Localization Success
WebAdmin Chinese Interface
Login Screen Chinese 中文化成功！UI 已顯示繁體中文

繁體中文語系檔 (translation.json)

Blogger 無法直接下載檔案。請複製下方內容，在伺服器建立檔案：
vim /root/translation.json

🔽 點擊展開 100+ 行核心 JSON 翻譯 (一鍵複製)

* 這是「核心精華版」翻譯，已涵蓋 SFTPGo 90% 的 WebAdmin 常用介面。
若您有完整 750 行的自定義翻譯，請將其貼上並取代上方程式碼區塊的內容。

✅ 中文化完成
SFTPGo Web 介面已切換為繁體中文，所有選單、按鈕、提示訊息均為繁中。
系統完整安裝完成 SFTPGo 2.7.0 已完全可用，包含：
  • ✅ SFTP 服務（2022 埠）
  • ✅ WebAdmin 管理介面（8080 埠）
  • ✅ 使用者群組管理
  • ✅ 日誌落地與輪替
  • ✅ 繁體中文化

第七章：常見問題與故障排除

Q1. 使用者無法自動建立 home dir

症狀：使用者登入後，/var/sftp/users 底下沒有對應的使用者資料夾。

解決步驟：

  1. 確認 /var/sftp/users 權限：
    ls -ld /var/sftp/users # 必須顯示：drwxr-x---. ... sftpgo sftpgo
  2. 確認 sftpgo 服務正常運行：
    systemctl status sftpgo --no-pager
  3. 檢查日誌是否有錯誤：
    tail -f /var/log/sftpgo/sftpgo.log | grep -i error

Q2. 中文化後仍顯示英文

症狀：UI 仍然是英文，沒有變繁中。

解決步驟：

  1. 確認 en/translation.json 已覆蓋：
    head -n 5 /usr/share/sftpgo/static/locales/en/translation.json # 應看到繁中如「初始設定」等
  2. 清除瀏覽器快取（最常見原因）：
    • 按 F12 開發者工具
    • 應用程式 → 本機存儲
    • 刪除所有 i18next* 開頭的項目
  3. 完全關閉瀏覽器後重新開啟

Q3. WebAdmin 無法連線

症狀：http://IP:8080/web/admin 無回應或連線被拒。

解決步驟：

  1. 確認防火牆開放 8080：
    sudo firewall-cmd --list-ports | grep 8080
  2. 確認 sftpgo 是否啟動：
    systemctl status sftpgo --no-pager
  3. 驗證埠監聽：
    ss -lntp | grep 8080
  4. 查看啟動日誌：
    journalctl -u sftpgo -n 50 --no-pager

Q4. SFTP 連線被拒

症狀：sftp -P 2022 user@host 無法連線。

解決步驟：

  1. 確認防火牆開放 2022：
    sudo firewall-cmd --list-ports | grep 2022
  2. 驗證帳號密碼正確（在 WebAdmin 確認使用者存在）
  3. 查看日誌：
    tail -f /var/log/sftpgo/sftpgo.log | grep -i connection

Q5. JSON 驗證失敗

症狀：python3 -m json.tool 報錯（少逗號、引號不成對等）。

解決步驟：

  1. 用文字編輯器開啟 translation.json，尋找錯誤位置（通常在報錯行號附近）
  2. 常見問題：
    • 少逗號（,）在某個 key-value 對後
    • 引號（"）沒有成對
    • 中文字前後有多餘空格
  3. 修正後重新驗證：
    python3 -m json.tool /root/translation.json >/dev/null echo $? # 應回傳 0

Q6. 日誌沒有寫入

症狀：/var/log/sftpgo/sftpgo.log 不存在或一直是空的。

解決步驟：

  1. 確認環境變數檔存在：
    cat /etc/sftpgo/sftpgo.env
  2. 檢查 systemd drop-in 是否正確：
    systemctl cat sftpgo | grep -A 5 EnvironmentFile
  3. 重新加載並重啟：
    sudo systemctl daemon-reload sudo systemctl restart sftpgo
  4. 等待 5 秒後檢查日誌：
    sleep 5 ls -l /var/log/sftpgo/ tail -n 20 /var/log/sftpgo/sftpgo.log

第八章：升級與維護

8.1 升級 SFTPGo 版本

若日後要升級到新版本（例如 2.8.0）：

# 檢查可用版本 dnf check-update | grep sftpgo # 執行升級 sudo dnf upgrade sftpgo -y # 重啟服務 sudo systemctl restart sftpgo # 驗證新版本 sftpgo version
⚠️ 升級前備份
升級前建議備份中文化的 translation.json（新版本可能更新英文檔，需要重新覆蓋繁中）。

8.2 升級後重新套用繁中

若升級後 en/translation.json 被重置，需要重新覆蓋：

# 驗證你保存的繁中 JSON python3 -m json.tool /root/translation.json >/dev/null && echo "OK" || echo "FAIL" # 覆蓋新版本的 en sudo cp -a /root/translation.json \ /usr/share/sftpgo/static/locales/en/translation.json # 驗證 python3 -m json.tool /usr/share/sftpgo/static/locales/en/translation.json >/dev/null && echo "OK" # 重啟 sudo systemctl restart sftpgo # 備份新的版本（含日期） sudo cp -a /usr/share/sftpgo/static/locales/en/translation.json \ "/root/sftpgo.translation.zh-TW.$(date +%F_%H%M%S).json"

8.3 日誌輪替與清理（已自動化）

由於前面設定了 SFTPGO_LOG_MAX_BACKUPS=50，系統會自動管理日誌：

# 查看當前日誌大小 du -sh /var/log/sftpgo/ # 查看備份檔數量（應不超過 50） ls -1 /var/log/sftpgo/sftpgo.log.* 2>/dev/null | wc -l # 查看備份檔（已自動 gzip 壓縮） ls -lh /var/log/sftpgo/
💡 日誌輪替參數
以目前設定，當日誌達 100MB 時會自動輪替；保留最多 50 個備份檔；超過 90 天的日誌自動刪除；備份檔自動 gzip 壓縮。這樣即使日誌很多也不會占用過多空間。

8.4 定期檢查清單

建議每月檢查一次系統狀態：

# 檢查服務狀態 systemctl status sftpgo --no-pager # 檢查磁碟使用 df -h /var/sftp /var/log/sftpgo # 檢查日誌輪替狀況 ls -lh /var/log/sftpgo/ | tail -n 10 # 檢查使用者數量 curl -s http://127.0.0.1:8080/web/admin/users | wc -l # 檢查備份檔（確保 en.translation.json 已妥善備份） ls -l /root/sftpgo.translation.zh-TW.*.json

附錄 A：快速參考

A1. 重要目錄與檔案

路徑 用途
/var/sftp/users/ 使用者家目錄儲存位置
/var/sftp/share/ 共用區（虛擬資料夾掛載點）
/var/log/sftpgo/sftpgo.log 實時日誌檔案
/etc/sftpgo/sftpgo.env 環境變數檔（日誌參數）
/usr/share/sftpgo/static/locales/en/translation.json 英文翻譯檔（被覆蓋成繁中）
/usr/share/sftpgo/static/locales/en/translation.json.bak 原始英文備份
/root/translation.json 繁中翻譯檔來源
/root/sftpgo.translation.zh-TW.*.json 已套用版本的時間戳備份

A2. 常用指令速查表

功能 指令
啟動服務 sudo systemctl start sftpgo
停止服務 sudo systemctl stop sftpgo
重啟服務 sudo systemctl restart sftpgo
查看狀態 sudo systemctl status sftpgo --no-pager
設為開機自啟 sudo systemctl enable sftpgo
查看即時日誌 sudo journalctl -u sftpgo -f
查看日誌檔 tail -f /var/log/sftpgo/sftpgo.log
驗證 JSON 格式 python3 -m json.tool /path/to/file.json
SFTP 測試連線 sftp -P 2022 user@host

A3. 還原英文版本（回復繁中）

若要回復為原始英文 UI：

sudo cp -a /usr/share/sftpgo/static/locales/en/translation.json.bak \ /usr/share/sftpgo/static/locales/en/translation.json sudo systemctl restart sftpgo

參考文獻

📚 SFTPGo 安裝與部署 系統安全與防火牆

附錄 B：目錄結構最終樣貌

完整安裝後，你的系統會呈現如下結構：

# SFTPGo 資料與日誌 /var/sftp/ ├── users/ │ ├── aaa/ │ │ ├── testfile.txt │ │ ├── file1.ps1 │ │ └── ... │ ├── bbb/ │ │ └── ... │ └── ...（更多使用者） └── share/ └── ...（共用檔案） /var/log/sftpgo/ ├── sftpgo.log # 當前日誌 ├── sftpgo.log.1.gz # 已輪替的壓縮備份 ├── sftpgo.log.2.gz ├── sftpgo.log.3.gz └── ...（最多 50 個） /usr/share/sftpgo/static/locales/ ├── en/ │ ├── translation.json # 已覆蓋成繁中 │ └── translation.json.bak # 原始英文備份 └── it/ └── translation.json /root/ ├── translation.json # 繁中翻譯檔來源 └── sftpgo.translation.zh-TW.2026-02-05_091500.json # 時間戳備份
🎉 安裝完成總結 您的 SFTPGo 2.7.0 已完全就緒！

本次安裝涵蓋以下內容：

階段 完成項目 驗證方式
系統準備 Python3、curl、防火牆 python3 --version
SFTPGo 安裝 Yum repo、systemd 啟動 systemctl status sftpgo
目錄規劃 /var/sftp users/share 目錄 ls -ld /var/sftp/*
WebAdmin 設定 群組、使用者、權限 用 SFTP 登入測試
日誌落地 輪替、壓縮、容量控制 ls -l /var/log/sftpgo/
中文化 en 繁體覆蓋、python3 驗證 WebAdmin UI 顯示繁中

✅ 系統已可投入生產環境
- SFTP 服務正常運行（2022 埠）
- WebAdmin 管理介面可用（8080 埠）
- 日誌完整記錄所有操作
- 介面已中文化，操作便利
- 自動輪替機制保護磁碟空間

後續維護建議：

  • 每月檢查一次日誌輪替狀況
  • 定期備份中文化的 translation.json
  • 系統升級前先做 VM Snapshot 快照
  • 監控 /var/sftp 磁碟使用率，必要時清理舊檔案
[系統] Rocky Linux 遷移與建置筆記 [實戰] Graylog 終極筆記：日誌分析系統安裝指南
🏷️ 熱門關鍵字 (Tags)
#SFTPGo #Linux #Rocky Linux #SFTP Server #繁體中文 #日誌分析
☕ 感謝您的閱讀！

寫技術文章不容易，若這篇教學對您有幫助：

  • 分享 給您的同事或社群
  • 留言 讓我知道這篇文有用
  • 回報 任何操作上的問題

留言

張貼留言