Unofficial
本頁內容
  1. 01角色
  2. 02啟用雙重驗證
  3. 03啟用雙重驗證後的 Git、SVN 與 Bucket
  4. 04指令碼與 CI 使用的 API 權杖
  5. 05密碼錯誤與鎖定
  6. 06管理員可以做什麼
  7. 07管理員遭鎖定時

帳號、雙重驗證與 API 權杖

Bucket & Code Server IDE 有自己的帳號：同一帳號以相同名稱及密碼登入面板、Git、SVN、Bucket 與編輯器。QTS 帳號無法登入。本指南說明雙重驗證、啟用後 git 與 WebDAV 用戶端使用的密碼、指令碼的 API 權杖，以及密碼錯誤次數過多時的處理方式。

  1. 角色viewer、member、developer、admin
  2. 2FA手機產生的驗證碼
  3. 用戶端存取權杖、應用程式密碼
  4. 權杖供指令碼與 CI 使用
  5. 鎖定以及恢復存取

圖片取自依本指南填寫各欄位的面板。開發者名稱是 ola ，管理員是 ewa；QR 碼已模糊處理，金鑰、應用程式密碼與權杖都是範例。雙重驗證與應用程式密碼的圖片來自面板的測試資料。

01角色

角色允許的操作
viewer / memberviewer 可讀取面板；Backups、Storage、Users 與 Logs 僅供管理員使用。member 也能寫入已獲授寫入權限的 Git、SVN 與 Bucket，但無法使用編輯器、cron 工作或建置功能。這兩種角色都無法建立 Git 儲存庫或組織。member 無法推送至 developer 以下帳號擁有或管理的 Git 儲存庫；啟用 CI 時，也無法推送至已啟用 Actions 的儲存庫
developer還能開啟編輯器、建置應用程式、執行自己的 cron 工作，並將套件發布至 NAS 的儲存庫（由管理員加入清單）
admin所有操作：帳號、設定、儲存空間、網路、模組、啟用應用程式及載入核心模組

developer 角色在 NAS 上具有 root 權限：編輯器終端機、開發者的 cron 指令，以及其可推送儲存庫的 CI 工作流程，全部以 root 執行。只應將此角色授予您願意交付 NAS 管理員密碼的人。在將任何內容發布至網際網路之前，請先為所有 developer 與 admin 啟用雙重驗證。

02啟用雙重驗證

每個帳號自行在 Your account （活動列底部的按鈕）啟用。

  1. 按下 Set up two-factor authentication。 雙重驗證卡片：目前關閉，以及設定按鈕
  2. 使用手機上的驗證器應用程式掃描 QR 碼，或在應用程式中輸入金鑰。輸入目前顯示的 6 位數驗證碼，再按下 Turn on。確認驗證碼之前，登入方式維持原狀。 設定雙重驗證：模糊處理的 QR 碼、範例金鑰、應用程式驗證碼欄位，以及啟用和取消按鈕
  3. 從現在起，登入時會在密碼之後要求驗證碼。 雙重驗證卡片：已啟用、git、SVN 與 Bucket 的變更，以及關閉按鈕登入第二步：驗證器驗證碼、以 ola 登入、驗證碼欄位與確認按鈕
  • 驗證碼共有 6 位數，每 30 秒更換一次。提前或延後 30 秒的驗證碼仍可使用。同一驗證碼不會接受兩次。
  • 如果新產生的驗證碼仍失敗，手機時間可能不準確：請開啟自動設定時間。
  • 關閉雙重驗證需要您的密碼。

03啟用雙重驗證後的 Git、SVN 與 Bucket

啟用雙重驗證後，git、SVN 與 WebDAV 用戶端不再接受帳號密碼，改用以下方式：

  • 透過 HTTP 或 HTTPS 使用 Git： 使用 Forgejo 存取權杖，在 Forgejo 的 Settings → Applications中建立。SSH 金鑰的使用方式不變。
  • SVN 與 WebDAV 用戶端： 使用在 Your account 建立的應用程式密碼。密碼由 25 個隨機字元組成，分為五組，只顯示一次。新密碼會取代舊密碼；變更帳號密碼或關閉雙重驗證會刪除它。 WebDAV 與 SVN 應用程式密碼卡片：尚未建立密碼，以及建立按鈕 立即複製應用程式密碼：範例密碼及已複製的確認

04指令碼與 CI 使用的 API 權杖

指令碼或 CI 工作使用 API 權杖代替密碼。在 Your account 按下 New token，以用途為其命名，並選擇權限範圍。

新 API 權杖：名稱 ci-deploy，勾選 read 與 write，未勾選 admin，以及建立按鈕立即複製權杖：bvs_ 後接 40 位十六進位數字的範例權杖，以及測試用 curl 指令
  • 權限範圍 read、write 與 admin 分別對應 viewer、developer 與 admin 角色。權杖以最高的範圍運作，但不會超過擁有者目前的角色。沒有對應 member 的範圍；member 只能建立 read 權杖。
  • 權杖只顯示一次，bvsd 僅保留雜湊值。指令碼以下列格式傳送： Authorization: Bearer bvs_…。
  • 新密碼會撤銷擁有者的所有權杖；停用帳號後，其權杖也無法再使用。
  • 權杖無法變更密碼或雙重驗證，也無法建立或刪除權杖，因此外洩的權杖無法將擁有者鎖在帳號外。請刪除不再使用的權杖；之後仍傳送它的程式會收到 401。
您的 API 權杖：ci-deploy，範圍為 read 與 write，於 2026 年 10 月 8 日建立，尚未使用，以及刪除按鈕

05密碼錯誤與鎖定

  • 同一位址在 15 分鐘內登入失敗五次，該位址就會鎖定 15 分鐘，即使密碼正確也無法登入。IPv6 用戶端以其 /64 網段計算。
  • 同一位址對同一帳號失敗五次，會禁止該位址登入該帳號 15 分鐘。
  • 多個位址對同一帳號登入失敗，會讓後續登入增加 125 毫秒至 2 秒的延遲。來自區域網路的失敗不會鎖定帳號。
  • 從上次成功登入起，同一帳號由網際網路登入失敗 20 次，就會鎖定其網際網路存取，不論來自哪些位址。帳號仍可從區域網路登入。次數可在 Users 頁面設定；0 會關閉此鎖定功能。 網際網路登入：設定失敗 20 次後鎖定帳號，以及儲存按鈕

位於反向代理後方時，只有在代理已設為受信任的情況下，面板才會計算代理回報的位址。否則所有用戶端都算成代理本身的位址，任何人輸入五次錯誤密碼都會將所有人鎖在外面。

06管理員可以做什麼

管理員在 Users 頁面按下帳號所在列，即可開啟該帳號。

  • 手機遺失時：在 Two-factor authentication 下選擇 Turn it off 。在帳號重新設定之前，只需密碼就能登入。 雙重驗證已啟用、遺失手機的提示，以及關閉按鈕
  • 帳號的網際網路存取遭鎖定時：選擇 Unlock或設定新密碼。
  • Set a new password 會結束帳號的工作階段並撤銷其 API 權杖。
  • 停用帳號會立即結束其工作階段並停止權杖；資料仍會保留。最後一個啟用中的 admin 無法降級、停用或刪除。
  • 停用帳號或角色改為 member 或 viewer 的帳號，其 cron 工作會保留但不會執行。刪除帳號也會刪除其工作（1.0.0-52 版起，請參閱 排程工作）。

07管理員遭鎖定時

NAS 管理員可從 NAS 上的 SSH 工作階段重設任何帳號。這些指令透過只有 root 能開啟的 socket 與 bvsd 通訊，每筆都會記錄在資料目錄內的 log/audit.log ：

/usr/bin/bucketvs/bin/bvs user list
/usr/bin/bucketvs/bin/bvs user password administrator
/usr/bin/bucketvs/bin/bvs user totp-reset administrator
/usr/bin/bucketvs/bin/bvs user unlock administrator
  • bvs user password 會設定並顯示一組新的 20 字元隨機密碼。帳號下次登入時必須自行選擇密碼；其工作階段會結束，API 權杖也會撤銷。
  • bvs user totp-reset 會關閉該帳號的雙重驗證。
  • bvs user unlock 會解除網際網路密碼錯誤次數過多造成的鎖定。