手冊

GeckoFlag 是安裝在您自己伺服器上的自行代管軟體；專用的安裝程式會引導您完成整個流程，讓任何人都能輕鬆完成設定。

開始之前

• 請確認您的伺服器符合系統需求。不需要 Composer：發行套件已內含其相依套件（vendor 資料夾），因此在無法執行 Composer 的環境中也能運作。
• 請準備好資料庫連線資訊：一個全新的資料庫，或是一個現有且為空的資料庫。我們不建議與其他應用程式共用資料庫。
• HTTPS 並非絕對必要，但由於 GeckoFlag 會處理登入憑證與個人資料，我們強烈建議以 HTTPS 執行。
• 上傳檔案後，請立即完成安裝。在安裝完成之前，任何知道網址的人都能開啟安裝程式。
• 如果您使用 Nginx，請事先完成下方「使用 Nginx 時」中的設定。

安裝步驟

1. 1透過 FTP/SFTP 或主機的控制面板，將 GeckoFlag 檔案上傳至您的伺服器並解壓縮。
2. 2在瀏覽器中開啟安裝程式。它會檢查您伺服器的環境（PHP 版本、必要擴充功能與資料夾權限），並顯示檢查清單。
3. 3輸入您的資料庫連線資訊（主機、連接埠、資料庫名稱、使用者名稱與密碼），然後繼續。
4. 4點擊 執行 以初始化資料庫；這會建立 GeckoFlag 所需的資料表。
5. 5以姓名、電子郵件與密碼建立您的管理員帳號。
6. 6輸入您的授權金鑰以進行驗證。
7. 7授權驗證完成後，一切準備就緒：使用您的新管理員帳號登入，並開始設定您的專案。

使用 Nginx 時

在 Apache 上，GeckoFlag 隨附的 .htaccess 會自動拒絕對設定檔、記錄檔等的直接存取。Nginx 不會使用 .htaccess，因此請將下列內容加入伺服器設定。若未加入，設定檔或上傳的檔案可能會被外部看到。

在結合 Nginx 與 Apache 的共享主機（由 Apache 處理 Nginx 所接收之存取的架構）上，.htaccess 會生效，因此不需要此設定。是否可以使用 .htaccess，請參閱您所使用主機供應商的說明文件。

• 請將公開資料夾（文件根目錄）設為 GeckoFlag 資料夾內的 webroot 資料夾，而非 GeckoFlag 資料夾本身。
• 請依您的環境修改 server_name（網域）、root（GeckoFlag 的放置位置）與 fastcgi_pass（PHP-FPM 的連線目標）。
• HTTPS 設定（listen 443 ssl 與憑證的指定）請依照您環境的設定方式另行加入。

server {
    listen 80;
    server_name pm.example.com;

    # 公開資料夾（文件根目錄）為 GeckoFlag 的 webroot 資料夾
    root /var/www/geckoflag/webroot;
    index index.php;

    # 不顯示資料夾內容清單
    autoindex off;

    # 讓更新與備份的 ZIP 檔案可以上傳
    # （Nginx 的預設值為 1MB）。PHP 的 upload_max_filesize 與
    # post_max_size 也請設為相同或更大的值
    client_max_body_size 100m;

    # 不提供隱藏檔案（.htaccess、.git 等）
    location ~ /\.(?!well-known/) {
        deny all;
    }

    # 上傳圖片的資料夾僅提供圖片
    location ~ ^/img/(avatars|project_thumbnails|branding)/ {
        location ~* \.(jpe?g|jfif|png|gif|webp|ico)$ {
            add_header X-Content-Type-Options "nosniff" always;
            try_files $uri =404;
        }
        # SVG 圖片僅供顯示（不允許執行指令碼）
        location ~* \.svg$ {
            add_header X-Content-Type-Options "nosniff" always;
            add_header Content-Security-Policy "default-src 'none'; img-src data:; style-src 'unsafe-inline'; sandbox" always;
            try_files $uri =404;
        }
        return 403;
    }

    # 不直接提供 files 資料夾
    location ^~ /files/ {
        return 404;
    }

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    # 僅將 index.php 作為 PHP 執行
    location = /index.php {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root/index.php;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }
    location ~ \.php$ {
        return 404;
    }
}

變更設定後，請以 nginx -t 檢查語法，然後重新載入 Nginx。