修復 BigBlueButton Greenlight 控制面板 500 內部伺服器錯誤

錯誤代碼500 Internal Server Error500 表示伺服器端請求失敗，但不會指明是哪個元件出了問題。對於 BigBlueButton Greenlight 控制面板，首先需要在 Greenlight 應用程式日誌中尋找失敗的請求。 BigBlueButton 的故障排除指南指出，500 錯誤很可能是 Greenlight 錯誤。異常資訊很有用：如果只有本機網路上的部分電腦看到此錯誤，且日誌報告“不安全主機錯誤”，則可能與瀏覽器代理設定有關。

Greenlight v3 是目前官方文件記錄的版本，其部署方式與先前的 v2 版本有所不同。本指南將協助您識別目前版本、收集相關證據並依序排查常見原因。本指南假設您使用的是基於 Docker 的 Greenlight 部署。請以伺服器管理員身分使用命令，並根據您的實際安裝情況調整容器名稱和路徑。

了解哪個元件回傳了 500

Greenlight 是用於登入、管理會議室和發起 BigBlueButton 會議的 Web 應用程式。反向代理（例如 Nginx）接收瀏覽器請求並將其轉發給 Greenlight。 Greenlight 隨後與 BigBlueButton 的 API 通信，並依賴 PostgreSQL 和 Redis 等服務。 500 錯誤可能源自 Greenlight、代理或相依性；重新啟動 BigBlueButton 媒體服務無法修復資料庫或應用程式異常。

首先記下觸發錯誤的操作：開啟控制台、登入、載入會議室清單或開始會議。記錄 URL 路徑、大致時間、是否所有使用者都受到影響，以及最近的任何更改，例如昇級、DNS 編輯、代理更改或憑證輪換。如果主頁可以加載，但某個操作返回 500 錯誤，則可以縮小需要調查的請求範圍。

在更改任何內容之前請做好準備。

確認鏡像版本是bigbluebutton/greenlight:v3v2 版本還是自訂版本。請勿將 v2 版本的說明套用至 v3 版本。
在編輯相關的 Docker Compose 檔案和環境變數檔案之前，請將其副本儲存在安全的位置。這些文件包含憑證。
記錄錯誤時間戳，並僅檢查其前後一小段日誌。共享日誌前，請對密碼、存取權杖、API金鑰、電子郵件地址和私人會議連結進行編輯。
請勿執行任何docker compose down -v操作來「重設」控制面板，例如刪除資料庫磁碟區或刪除 Greenlight 儲存體。這些操作可能會破壞帳戶、設定或已上傳的資產。

步驟 1：檢查正在運作的容器並捕獲異常

在 Docker 主機上，列出與 Greenlight 相關的容器及其映像和狀態：

sudo docker ps -a --filter name=greenlight \
  --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'

對於標準的 Greenlight v3 安裝，應用程式容器通常命名為greenlight-v3。請閱讀其在故障發生前後的近期輸出：

sudo docker logs --since=15m --tail=200 greenlight-v3

如果您的安裝使用了 Compose，請在包含 Compose 檔案的目錄中執行docker compose ps` docker compose logs --since=15m --tail=200bigbluebutton install` 命令。 BigBlueButton 安裝可能會將 v3 檔案保存在 `<path>` 下~/greenlight-v3；獨立安裝的情況可能有所不同。請使用主機報告的實際位置和容器名稱。對於較舊的 v2 安裝，請檢查已掛載的 Rails 日誌（通常位於 Greenlight 安裝目錄中），如果未掛載，log/production.log請檢查容器內的日誌。/usr/src/app/log/production.log

請尋找請求失敗時出現的第一個異常，而不僅僅是最終的 500 回應。資料庫連線錯誤、Redis 錯誤、API 請求失敗、憑證驗證錯誤和 Rails 異常都指向不同的修復方案。如果容器已退出，其日誌可能仍可透過以下方式存取docker logs：

步驟 2：檢查 Greenlight 與 BigBlueButton 的連接

如果在載入會議室或開始會議時控制面板發生故障，請驗證 Greenlight 使用的 BigBlueButton URL 和共用金鑰。對於 v3 版本，環境檔案包含 `<your-bigbluebutton-url>` 和 `<your-bigbluebutton-shared-secret>` BIGBLUEBUTTON_ENDPOINT。BIGBLUEBUTTON_SECRET端點必須是您部署的 API URL，而不是猜測的主機或僅限瀏覽器存取的會議 URL。如果您使用負載平衡器（例如 Scalelite），請使用該設定提供的端點和憑證。

在 BigBlueButton 伺服器上，sudo bbb-conf --secret顯示已設定的 URL 和金鑰。請私下將其與 Greenlight 的值進行比較。切勿將金鑰貼到工單、shell 日誌或公開聊天中。重新安裝或憑證輪替後，過期的金鑰可能會導致 API 呼叫失敗，即使儀表板容器運作正常。

此指令也需要sudo bbb-conf --check在 BigBlueButton 主機上執行。它會檢查 BigBlueButton 服務和常見的設定問題；但它並不能取代檢查 Greenlight 日誌。如果 Greenlight 位於單獨的獨立主機上，則此命令應在bbb-conf安裝了 Greenlight 的 BBB 伺服器上執行。

步驟 3：檢查資料庫、Redis 和最近的升級

Greenlight v3 的範例環境定義了資料庫和快取連線DATABASE_URL。REDIS_URL請確認 PostgreSQL 和 Redis 容器正在運行，並且應用程式環境中的值與 Compose 中的服務名稱、連接埠、資料庫名稱和憑證相符。即使 Greenlight 容器看起來運作正常，如果無法連接到這些依賴項之一，仍然可能會傳回 500 錯誤。

如果錯誤是在升級後出現的，請將已部署的鏡像標籤、Compose 檔案和環境變數檔案與您遵循的發布流程進行比較。在診斷生產環境問題時，請避免拉取任意鏡像或手動更改資料庫架構。請先備份資料庫，然後依照 Greenlight 文件中提供的升級流程進行安裝。同時，請檢查磁碟空間：磁碟空間不足可能會導致 PostgreSQL 寫入、日誌寫入或資產儲存更新失敗。

步驟 4：檢查代理程式、主機名稱和子路徑設置

如果錯誤僅透過公用主機名稱出現，請檢查瀏覽器經由反向代理到 Greenlight 的路徑。確認代理已轉送到正確的內部端口，並保留了預期的主機頭和協定頭。在重新載入 Nginx 之前測試代理程式配置sudo nginx -t，然後檢查匹配時間戳記的代理錯誤日誌。

Greenlight v3 預設運行在根路徑下。如果它發佈在類似 `/etc/greenlight/` 這樣的路徑下/gl，則其 `/ RELATIVE_URL_ROOTetc/greenlight/` 和反向代理規則必須一致。官方安裝指南指出，相對 URL 根路徑的變更需要透過安裝程序進行升級/重新配置；僅設定 shell 變數無法修復現有部署的不匹配問題。不匹配通常會導致重定向或資源損壞，但代理請求失敗也可能表現為應用程式錯誤。

BigBlueButton 文件中記錄了一個特定的區域網路案例：如果只有部分位於代理伺服器後面的電腦收到 500 錯誤，並且 Greenlight 日誌中包含相關信息Error::Unsafe Host Error，請檢查 Windows 是否設定為對本地或內網位址繞過代理。這是一個客戶端網路路徑問題，並非需要全域停用主機驗證的理由。

步驟 5：檢查身份驗證和電子郵件更改

如果在登入過程中出現 500 錯誤，請檢查 OpenID Connect 設定、回呼 URL 或身分提供者的近期變更。 Greenlight v3 在設定外部身分驗證時會使用諸如 ` OPENID_CONNECT_ISSUER<your-external-authentication-url> OPENID_CONNECT_CLIENT_ID`、`<your-external-authentication-url>` 和`<your-external-authentication-url>` 之類的值OPENID_CONNECT_REDIRECT。確認重新導向 URL 與公用 Greenlight URL（包括任何已配置的子路徑）匹配，並檢查 Greenlight 和身分識別提供者日誌中是否存在相同的時間戳記。

Greenlight v3 文件指出，基本平台功能需要電子郵件。如果在邀請、註冊、密碼重設或其他電子郵件操作期間控制面板發生故障，請檢查 SMTP 連線和憑證、TLS 設定以及應用程式日誌。務必妥善保管 SMTP 金鑰。如果故障僅限於與郵件相關的操作，則提示在變更 BigBlueButton API 憑證之前，應先檢查郵件設定。

只有在確定可能原因後才能重新啟動

確認環境或代理問題後，請使用此安裝對應的 Compose 檔案重新啟動受影響的 Greenlight 服務。例如，從 v3 安裝目錄：

cd ~/greenlight-v3
sudo docker compose ps
sudo docker compose restart greenlight-v3

Compose 服務名稱可能與容器名稱不同。如果重新啟動指令提示服務未知，請檢查docker compose config --services並重新啟動所列的 Greenlight 服務，或使用部署文件中提供的更新指令。除非日誌顯示有依賴關係問題且您已製定復原計劃，否則請避免重新啟動 PostgreSQL 或刪除磁碟區。

驗證修復方案並了解何時需要升級處理。

重複先前失敗的操作，然後在新的時間戳檢查瀏覽器中的回應和 Greenlight 日誌。確認使用者可以載入儀表板，如果先前的失敗與會議有關，則發起一次測試會議。如果測試會議bbb-conf --check成功，但應用程式仍傳回 500 錯誤，則表示問題可能出在 Greenlight、其依賴項或代理程式上。

如果問題仍然存在，請提供 Greenlight 版本或鏡像標籤、部署類型、受影響的 URL 路徑、故障發生時間、相關的已編輯異常資訊、容器狀態以及最近的變更。請勿共用完整的環境檔案、API 金鑰、資料庫密碼、使用者會話 cookie 或未編輯的日誌。

請使用BigBlueButton 故障排除指南了解 500 錯誤的官方解釋，並使用Greenlight v3 安裝和設定文件來了解目前 v3 部署模型。專案的Greenlight v3 範例環境檔案列出了支援的環境變數。 Greenlight v2 和 v3 有所不同，因此請使用與您部署的版本相符的文件。