docs: Sync zh-cn and zh-tw current and 1.27 with English (#545)

Co-authored-by: Lunny Xiao <[email protected]> Reviewed-on: https://gitea.com/gitea/docs/pulls/545 Reviewed-by: Lunny Xiao <[email protected]> Co-authored-by: kmiit <[email protected]>
2026-09-17 19:55:34 +00:00 · 2026-09-14 19:50:42 +00:00
parent 42591cadac
commit 1a284521f1
4 changed files with 284 additions and 66 deletions
@@ -14,6 +14,8 @@ aliases:
 2. 將 `https://git.example.com/foo` 反向代理到 `http://gitea:3000/foo`
 3. 確保反向代理不會解碼 URI。`https://git.example.com/a%2Fb`的請求應該被傳遞給 `http://gitea:3000/a%2Fb`。
 4. 確保 `Host` 和 `X-Forwarded-Proto` 頭被正確的傳遞給 Gitea，使 Gitea 可以看到正在訪問的真實 URL。
+5. 確保 Web 伺服器有完整的憑證（包括所有中間憑證和根憑證），以便 `git clone` 和 `git pull` 正常工作。
+6. Gitea 會在 `/-/ws` 使用 WebSocket 連線，用於通知計數等即時更新。請確保反向代理使用 HTTP/1.1，並轉發 `Upgrade` 和 `Connection` 頭，參見下面的示例。否則 Gitea 會改為定期輪詢。

 ## 使用子路徑

@@ -39,6 +41,7 @@ server {
    location / {
        client_max_body_size 512M;
        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
        proxy_set_header Connection $http_connection;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Host $host;
@@ -61,8 +64,9 @@ server {

        # 確保 nginx 使用未轉義 URI， 按原樣保持 "%2F"。 確保 nginx 去除 "/gitea" 子路徑前綴， 按原樣傳遞 "/v2"。
        rewrite ^ $request_uri;
-        rewrite ^(/gitea)?(/.*) $2 break;
+        rewrite ^/(gitea($|/))?(.*) /$3 break;
        proxy_pass http://127.0.0.1:3000$uri;
+        proxy_http_version 1.1;

        # 其他的常規 HTTP 表頭，見上面“使用 Nginx 作為反向代理服務”小節的配置
        proxy_set_header Connection $http_connection;
@@ -107,6 +111,7 @@ server {
    }

    location / {
+        # 其他指令見上面「使用 Nginx 作為反向代理服務」小節
        proxy_pass http://localhost:3000;
    }
 }
@@ -123,6 +128,7 @@ server {
    server_name git.example.com;

    location / {
+        # 其他指令見上面「使用 Nginx 作為反向代理服務」小節
        proxy_pass http://localhost:3000;
    }
 }
@@ -144,6 +150,20 @@ server {
 }
 ```

+## Nginx Proxy Manager
+
+如果使用 Nginx Proxy Manager 作為 Gitea 的反向代理，設定與原生 Nginx 略有不同。
+
+它會[預設給自訂 location 加上一些指令](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/master/docker/rootfs/etc/nginx/conf.d/include/proxy.conf)，因此上面 Nginx 設定裡對應的指令不要再寫一遍。否則會因為指令重複（尤其是 `proxy_set_header Host $host`）出現 `400 bad request`。
+
+建立 `/` 自訂 location 時，只需在其設定中加入：
+
+```nginx
+client_max_body_size 512M;
+```
+
+在代理主機上啟用 `Websockets Support`，Nginx Proxy Manager 會自行加入 WebSocket 相關指令。再額外添加 `proxy_http_version` 會導致 Nginx 拒絕啟動。
+
 ## 使用 Apache HTTPD 作為反向代理服務

 如果您想使用 Apache HTTPD 作為 Gitea 的反向代理服務，您可以為您的 Apache HTTPD 作如下設定（在 Ubuntu 中，設定文件通常在 `/etc/apache2/httpd.conf` 目錄下）：
@@ -154,30 +174,23 @@ server {
    ProxyPreserveHost On
    ProxyRequests off
    AllowEncodedSlashes NoDecode
-    ProxyPass / http://localhost:3000/ nocanon
+    ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
 </VirtualHost>
 ```

-注：必須啟用以下 Apache HTTPD 元件：`proxy`， `proxy_http`
+:::note
+必須啟用以下 Apache HTTPD 元件：`proxy`， `proxy_http`。
+
+`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本。更舊的版本**必須**去掉它，否則 Apache HTTPD 將無法啟動。
+:::
+
+如果希望用 Let's Encrypt 的 webroot 驗證，請在 `ProxyPass` 之前加入 `ProxyPass /.well-known !`，避免把這些請求代理到 Gitea。

 ## 使用 Apache HTTPD 作為反向代理服務並將 Gitea 路由至一個子路徑

 如果您已經有一個域名並且想與 Gitea 共享該域名，您可以增加以下設定為 Gitea 添加路由規則（在 Ubuntu 中，設定文件通常在 `/etc/apache2/httpd.conf` 目錄下）：

-```
-<VirtualHost *:80>
-    ...
-    <Proxy *>
-         Order allow,deny
-         Allow from all
-    </Proxy>
-    AllowEncodedSlashes NoDecode
-    # 注意: 路徑和 URL 後面都不要寫路徑符號 '/'
-    ProxyPass /git http://localhost:3000 nocanon
-</VirtualHost>
-```
-
 ```apacheconf
 <VirtualHost *:80>
    ...
@@ -187,7 +200,7 @@ server {
    </Proxy>
    AllowEncodedSlashes NoDecode
    # 注意: 路徑和 URL 後面都不要寫路徑符號 '/'
-    ProxyPass /git http://localhost:3000 nocanon
+    ProxyPass /git http://localhost:3000 nocanon upgrade=websocket
    ProxyPreserveHost On
    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
 </VirtualHost>
@@ -195,7 +208,55 @@ server {

 然後您**必須**在 Gitea 的設定文件中正確的添加類似 `[server] ROOT_URL = http://git.example.com/git/` 的設定項。

-注：必須啟用以下 Apache HTTPD 元件：`proxy`， `proxy_http`
+:::note
+必須啟用以下 Apache HTTPD 元件：`proxy`， `proxy_http`。`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本，更舊的版本請去掉它。
+:::
+
+## 使用 Apache HTTPD 直接提供靜態資源
+
+我們可以通過將資源分為靜態和動態兩種類型來調節性能。
+
+CSS 文件、JavaScript 文件、圖片和字體是靜態內容。首頁、倉庫視圖和工單列表是動態內容。
+
+Apache HTTPD 可以直接提供靜態資源，並且只代理動態資源請求給 Gitea。
+
+將 Gitea 源代碼倉庫的一個快照下載到 `/path/to/gitea/`。
+在此之後，在本地倉庫目錄運行 `make frontend` 來生成靜態資源。在這個情況下，我們只對 `public/` 目錄感興趣，您可以刪除剩下的其他目錄。
+（為了生成靜態資源，您需要安裝一個[帶 npm 的 Node ](https://nodejs.org/en/download/)和 `make`）
+
+取決於您的用戶量的大小，您可以將流量分離到兩個不同的服務器，或者為靜態資源設定一個 cdn。
+
+### 單伺服器節點，單域名
+
+將 `[server] STATIC_URL_PREFIX = /_/static` 寫入您的 Gitea 設定文件：
+
+```apacheconf
+<VirtualHost *:80>
+    ...
+    <Proxy *>
+         Order allow,deny
+         Allow from all
+    </Proxy>
+
+    ProxyPass /_/static/ !
+    Alias /_/static/ /path/to/gitea/public/
+    <Directory /path/to/gitea/public/>
+        Options FollowSymlinks
+		AllowOverride None
+		Require all granted
+    </Directory>
+
+    AllowEncodedSlashes NoDecode
+    # 注意: 路徑和 URL 後面都不要寫路徑符號 '/'
+    ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
+    ProxyPreserveHost On
+    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
+</VirtualHost>
+```
+
+:::note
+必須啟用以下 Apache HTTPD 元件：`proxy`， `proxy_http`。`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本，更舊的版本請去掉它。
+:::

 ## 使用 Caddy 作為反向代理服務

@@ -231,11 +292,13 @@ git.example.com {

 - 使用 Microsoft Web Platform Installer 5.1 (WebPI) 安裝 Application Request Routing（簡稱 ARR），或者在 [IIS.net](https://www.iis.net/downloads/microsoft/application-request-routing) 下載這個外掛。
 - 一但這個模組被安裝到 IIS 上，你將會在 IIS 管理控制檯看到一個叫做 URL Rewrite 的新圖標。
+- 安裝 Windows 功能 `WebSocket Protocol`，否則 ARR 無法代理 Gitea 的 WebSocket 端點。
 - 打開 IIS 管理控制檯，在左邊的列表中點擊 `Gitea Proxy` 網頁。在中間選中並且雙擊 URL Rewrite 的圖標來加載 URL 重寫的面板。
 - 在管理控制檯的右邊選擇 `Add Rule` 操作，並且在 `Inbound and Outbound Rules` 分類中選擇 `Reverse Proxy Rule`。
 - 在 Inbound Rules 中， 將 server name 設定為 Gitea 正在運行的主機以及對應端口。例如，如果你在 localhost 的 3000 端口上運行 Gitea，則設定為 `127.0.0.1:3000`。
 - 啟用 SSL Offloading
 - 在 Outbound Rules 中，確保設定了 `Rewrite the domain names of the links in HTTP response`，並且將 `From:` 設定為上面的 server name，將 `To:` 設定為你的外部訪問名稱，例如：`git.example.com`
+- 關閉 Application Request Routing 的 `Server Proxy Settings` 中的 `Reverse rewrite host in response headers`（在 IIS 管理員中選擇伺服器節點，打開 `Application Request Routing Cache`，再開啟右側的 `Server Proxy Settings`）。若保持開啟，ARR 會把 `Location` 頭裡的主機改回內部位址，導致登入或表單提交後的重新導向把瀏覽器送到 `127.0.0.1:3000` 而不是 `git.example.com`。
 - 現在，根據下面的內容為您的網頁編輯 `web.config`（將 `127.0.0.1:3000` 和 `git.example.com` 改為適當的值）

 ```xml