跳至主要内容
版本：1.28-dev

常見問題

本頁面包含一些常見問題和答案。

有關更多幫助資源，請查看所有支援選項。

1.x 和 1.x.x 下載之間的區別​

以 1.7.x 版本為例。

**注意：**此範例也適用於 Docker 鏡像！

在我們的下載頁面上，您會看到一個 1.7 目錄，以及 1.7.0、1.7.1、1.7.2、1.7.3、1.7.4、1.7.5 和 1.7.6 的目錄。

1.7 目錄和 1.7.0 目錄是不同的。1.7 目錄是在每個合併到release/v1.7分支的提交上構建的。

然而，1.7.0 目錄是在建立v1.7.0標籤時建立的構建。

這意味著 1.x 的下載會隨著提交合併到各自的分支而改變（將其視為每個版本的單獨的“main”分支）。

另一方面，1.x.x 的下載應該永遠不會改變。

如何從 Gogs/GitHub 等遷移到 Gitea​

要從 Gogs 遷移到 Gitea：

要從 GitHub 遷移到 Gitea，您可以使用 Gitea 內置的遷移表單。

為了遷移諸如問題、拉取請求等專案，您需要至少輸入您的使用者名稱。

Example (requires login)

要從 GitLab 遷移到 Gitea，您可以使用這個非關聯的工具：

https://github.com/loganinak/MigrateGitlabToGogs

Gitea 儲存文件的位置​

  • AppWorkPath
    • --work-path標誌
    • 或者環境變量GITEA_WORK_DIR
    • 或者在構建時設定的內置值
    • 或者包含 Gitea 二進制文件的目錄
  • %(APP_DATA_PATH)（資料庫、索引器等的預設路徑）
    • app.ini中的APP_DATA_PATH
    • 或者*AppWorkPath*/data
  • CustomPath（自訂模板）
    • --custom-path標誌
    • 或者環境變量GITEA_CUSTOM
    • 或者在構建時設定的內置值
    • 或者*AppWorkPath*/custom
  • HomeDir
    • Unix：環境變量HOME
    • Windows：環境變量USERPROFILE，或者環境變量HOMEDRIVE+HOMEPATH
  • RepoRootPath
    • app.ini中[repository]部分的ROOT（如果是絕對路徑）
    • 否則*AppWorkPath*/ROOT(如果app.ini中[repository]部分的ROOT是相對路徑）
    • 預設值為%(APP_DATA_PATH)/gitea-repositories
  • INI（設定文件）
    • --config標誌
    • 或者在構建時設定的可能內置值
    • 或者 CustomPath/conf/app.ini
  • SQLite 資料庫
    • app.ini 中 database 部分的 PATH
    • 或者%(APP_DATA_PATH)/gitea.db

看不到克隆 URL 或克隆 URL 不正確​

有幾個地方可能會導致顯示不正確。

  1. 如果使用反向代理，請確保按照反向代理指南中的正確說明進行設定。
  2. 確保在app.ini的server部分中正確設定了ROOT_URL。

如果某些克隆選項未顯示（HTTP/S 或 SSH），可以在app.ini中

  • DISABLE_HTTP_GIT: 如果設為 true, 將會沒有 HTTP/HTTPS 鏈接
  • DISABLE_SSH: 如果設為 true, 將會沒有 SSH 鏈接
  • SSH_EXPOSE_ANONYMOUS: 如果設為 false, SSH 鏈接將會對匿名使用者隱藏

文件上傳失敗：413 Request Entity Too Large​

當反向代理限制文件上傳大小時，會出現此錯誤。

有關使用 nginx 解決此問題，請參閱反向代理指南。

自訂模板無法加載或運行錯誤​

Gitea 的自訂模板必須將其添加到正確的位置，否則 Gitea 將無法找到並使用自訂模板。

模板的正確路徑應該相對於CustomPath。

  1. 要找到CustomPath，請在站點管理 -> 設定 中查找自訂文件根路徑。

    如果找不到，請嘗試echo $GITEA_CUSTOM。

  2. 如果仍然找不到，預設值可以被計算

  3. 如果仍然找不到路徑，則可以參考自訂 Gitea頁面，將模板添加到正確的位置。

Gitea 是否有"GitHub/GitLab Pages"功能？​

Gitea 不提供內置的 Pages 伺服器。您需要一個專用的域名來提供靜態頁面，以避免 CSRF 安全風險。

對於簡單的用法，您可以使用反向代理來重寫和提供 Gitea 的原始文件 URL 中的靜態內容。

還有一些已經可用的第三方服務，比如獨立pages server的或caddy plugin，可以提供所需的功能。

活躍使用者與禁止登入使用者​

在 Gitea 中，"活躍使用者"是指通過電子郵件激活其帳戶的使用者。

"禁止登入使用者"是指不允許再登入到 Gitea 的使用者。

設定日誌記錄​

什麼是 Swagger？​

Swagger 是 Gitea 用於其 API 文件的工具。

所有 Gitea 實例都有內置的 API，無法完全禁用它。 但是，您可以在 app.ini 的 api 部分將 ENABLE_SWAGGER 設定為 false，以禁用其文件顯示。 有關更多資訊，請參閱 Gitea 的API 文件。

您可以在上查看最新的 API（例如）https://gitea.com/api/swagger

您還可以在上查看swagger.json文件的範例 https://gitea.com/swagger.v1.json

調整伺服器用於公共/私有使用​

防止垃圾郵件發送者​

有多種方法可以組合使用來防止垃圾郵件發送者：

  1. 通過設定電子郵件域名的白名單或黑名單。
  2. 通過設定一些域名或者 OpenID 白名單（見下文）。
  3. 在您的app.ini中將ENABLE_CAPTCHA設定為true，並正確設定RECAPTCHA_SECRET和 RECAPTCHA_SITEKEY。
  4. 將DISABLE_REGISTRATION設定為true，並通過 CLI、API 或 Gitea 的管理介面建立新使用者。

僅允許/阻止特定的電子郵件域名​

您可以在app.ini中的[service]下的設定EMAIL_DOMAIN_WHITELIST 或 EMAIL_DOMAIN_BLOCKLIST。

僅允許/阻止特定的 OpenID 提供商​

您可以在app.ini的[openid]下設定WHITELISTED_URI或BLACKLISTED_URIS。

注意： 白名單優先，如果白名單非空，則忽略黑名單。

僅允許發佈問題的使用者​

目前實現這一點的方法是建立/修改一個具有最大儲存庫建立限制為 0 的使用者。

受限制的使用者​

受限制的使用者僅能訪問其組織/團隊成員和協作所在的內容的子集，而忽略組織/儲存庫等的公共標誌。

範例用例：一個公司運行一個需要登入的 Gitea 實例。大多數儲存庫是公開的（所有同事都可以訪問/瀏覽）。

在某些情況下，某個客戶或第三方需要訪問特定的儲存庫，並且只能訪問該儲存庫。通過將此類客戶帳戶設定為受限制帳戶，並使用團隊成員身份和/或協作來授予所需的任何存取權限，可以簡單地實現這一點，而無需使所有內容都變為私有。

啟用 Fail2ban​

使用 Fail2Ban 監視並阻止基於日誌模式的自動登入嘗試或其他惡意行為。

SSHD vs 內建 SSH​

SSHD 是大多數 Unix 系統上內建的 SSH 伺服器。

Gitea 還提供了自己的 SSH 伺服器，用於在 SSHD 不可用時使用。

Gitea 運行緩慢​

導致此問題的最常見原因是加載聯合頭像。

您可以透過在app.ini中將ENABLE_FEDERATED_AVATAR設定為false來關閉此功能。

還有一個可能需要更改的選項是在app.ini中將DISABLE_GRAVATAR設定為true。

無法建立儲存庫/文件​

請確保 Gitea 具有足夠的權限來寫入其主目錄和資料目錄。

參見AppDataPath 和 RepoRootPath

**適用於 Arch 使用者的注意事項：**在撰寫本文時，Arch 套件的 systemd 文件包含了以下行：

ReadWritePaths=/etc/gitea/app.ini

這將使得 Gitea 無法寫入其他路徑。

翻譯不正確/如何添加更多翻譯​

我們當前的翻譯是在我們的Crowdin 專案上眾包進行的

無論您想要更改翻譯還是添加新的翻譯，都需要在 Crowdin 整合中進行，因為所有翻譯都會被 CI 覆蓋。

推送鉤子/ Webhook / Actions 未運行​

如果您可以推送但無法在主頁儀表板上看到推送活動，或者推送不觸發 Webhook 和 Actions，可能是 git 鉤子不工作而導致的。

這可能是由於以下原因：

  1. Git 鉤子不同步：在站點管理面板上運行“重新同步所有儲存庫的 pre-receive、update 和 post-receive 鉤子”
  2. Git 儲存庫（和鉤子）儲存在一些不支援腳本執行的文件系統上（例如由 NAS 掛載），請確保文件系統支援chmod a+x any-script
  3. 如果您使用的是 Docker，請確保 Docker Server（而不是客戶端）的版本 >= 20.10.6

SSH 問題​

如果無法通過ssh訪問儲存庫，但https正常工作，請考慮以下情況。

首先，請確保您可以透過 SSH 訪問 Gitea。

ssh git@myremote.example

如果連接成功，您應該會收到以下錯誤消息：

Hi there, You've successfully authenticated, but Gitea does not provide shell access.
If this is unexpected, please log in with password and setup Gitea under another user.

如果您收到以上消息但仍然連接成功，這意味著您的 SSH 密鑰沒有由 Gitea 管理。這意味著鉤子不會運行，在其他一些潛在問題中也包括在內。

如果您無法連接，可能是因為您的 SSH 密鑰在本地設定不正確。 這是針對 SSH 而不是 Gitea 的問題，因此在此不涉及。

SSH 常見錯誤​

Permission denied (publickey).
fatal: Could not read from remote repository.

此錯誤表示伺服器拒絕登入嘗試， 請檢查以下事項：

  • 在客戶端：

    • 確保公鑰和私鑰已添加到正確的 Gitea 使用者。
    • 確保遠程 URL 中沒有任何問題。特別是，請確保 ∂ Git 使用者（@ 之前的部分）的名稱拼寫正確。
    • 確保客戶端機器上的公鑰和私鑰正確無誤。

  • 在伺服器上：

    • 確保儲存庫存在並且命名正確。
    • 檢查系統使用者主目錄中的 .ssh 目錄的權限。
    • 驗證正確的公鑰是否已添加到 .ssh/authorized_keys 中。

    嘗試在 Gitea 管理面板上運行 Rewrite '.ssh/authorized_keys' file (for Gitea SSH keys)。

  • 查看 Gitea 日誌。

  • 查看 /var/log/auth（或類似的文件）。

  • 檢查儲存庫的權限。

以下是一個範例，其中缺少公共 SSH 密鑰， 認證成功，但是其他設定導致 SSH 無法訪問正確的 儲存庫。

fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

在這種情況下，請檢查以下設定：

  • 在伺服器上：
    • 確保git系統使用者設定了可用的 shell
      • 使用getent passwd git | cut -d: -f7進行驗證
      • 可以使用usermod或chsh進行修改。
    • 確保.ssh/authorized_keys中的gitea serv命令使用 正確的設定文件。

遷移帶有標籤的儲存庫後缺失發佈版本​

要遷移帶有所有標籤的儲存庫，您需要執行兩個操作：

  • 推送標籤到儲存庫：
 git push --tags
  • 在 Gitea 中重新同步所有儲存庫的標籤：
gitea admin repo-sync-releases

LFS 問題​

針對涉及 LFS 資料上傳的問題

batch response: Authentication required: Authorization error: <GITEA_LFS_URL>/info/lfs/objects/batch
Check that you have proper access to the repository
error: failed to push some refs to '<GIT_REPO_URL>'

檢查app.ini文件中的LFS_HTTP_AUTH_EXPIRY值。

預設情況下，LFS 令牌在 20 分鐘後過期。如果您的連接速度較慢或文件較大（或兩者都是），可能無法在時間限制內完成上傳。

您可以將此值設定為60m或120m。

如何在啟動 Gitea 之前建立使用者​

Gitea 提供了一個子命令gitea migrate來初始化資料庫，然後您可以使用管理 CLI 命令像正常情況下添加使用者。

如何啟用密碼重置​

沒有密碼重置的設定。當設定了郵件服務時，密碼重置將自動啟用；否則將被禁用。

如何更改使用者的密碼​

  • 作為管理員，您可以更改任何使用者的密碼（並可選擇強制其在下次登入時更改密碼）...

    • 轉到您的站點管理 -> 用戶賬戶頁面並編輯使用者。

  • 使用管理 CLI 命令。

    請注意，大多數命令還需要一個全域標誌來指向正確的設定。

  • 作為使用者，您可以更改密碼...

    • 在您的帳號的設定 -> 帳號頁面（此方法需要您知道當前密碼）。
    • 使用忘記密碼鏈接。

    如果忘記密碼/賬戶恢復頁面被禁用，請聯繫管理員設定郵件服務。

為什麼我的 Markdown 顯示錯誤​

在 Gitea 版本 1.11 中，我們轉換為使用goldmark進行 Markdown 渲染，它符合CommonMark標準。

如果您在版本1.11之前的 Markdown 正常工作，但在升級後無法正常工作，請仔細閱讀 CommonMark 規範，看看問題是由錯誤還是非相容的語法引起的。

如果是後者，通常規範中會列出一種符合標準的替代方法。

使用 MySQL 進行升級時出現的錯誤​

如果在使用 MySQL 升級 Gitea 時收到以下錯誤：

ORM engine initialization failed: migrate: do migrate: Error: 1118: Row size too large...

請運行 gitea doctor convert 或對資料庫中的每個表運行 ALTER TABLE table_name ROW_FORMAT=dynamic;。

潛在問題是預設行格式分配給每個表的索引空間 太小。Gitea 要求其表的ROWFORMAT為DYNAMIC。

如果收到包含Error 1071: Specified key was too long; max key length is 1000 bytes... 的錯誤行，則表示您正在嘗試在使用 ISAM 引擎的表上運行 Gitea。儘管在先前版本的 Gitea 中可能是湊巧能夠工作的，但它從未得到官方支援， 您必須使用 InnoDB。您應該對資料庫中的每個表運行ALTER TABLE table_name ENGINE=InnoDB;。

為什麼 Emoji 只顯示佔位符或單色圖像​

Gitea 需要系統或瀏覽器安裝其中一個受支援的 Emoji 字體，例如 Apple Color Emoji、Segoe UI Emoji、Segoe UI Symbol、Noto Color Emoji 和 Twemoji Mozilla。通常，操作系統應該已經提供了其中一個字體，但特別是在 Linux 上，可能需要手動安裝它們。

SystemD 和 Docker 上的標準輸出日誌​

SystemD 上的標準輸出預設會寫入日誌記錄中。您可以嘗試使用 journalctl、journalctl -u gitea 或 journalctl <path-to-gitea-binary>來查看。

類似地，Docker 上的標準輸出可以使用docker logs <container>來查看。

要收集日誌以進行幫助和問題報告，請參閱支援選項。

初始日誌記錄​

在 Gitea 讀取設定文件並設定其日誌記錄之前，它會將一些內容記錄到標準輸出，以幫助調試日誌記錄無法工作的情況。

您可以透過設定--quiet或-q選項來停止此日誌記錄。請注意，這只會在 Gitea 設定自己的日誌記錄之前停止日誌記錄。

如果您報告了錯誤或問題，必須提供這些資訊以恢復初始日誌記錄。

只有在完全設定了所有內容之後，您才應該設定此選項。

在資料庫啟動期間出現有關結構預設值的警告​

有時，在遷移過程中，舊列和預設值可能在資料庫架構中保持不變。 這可能會導致警告，例如：

2020/08/02 11:32:29 ...rm/session_schema.go:360:Sync() [W] Table user Column keep_activity_private db default is , struct default is 0

可以安全地忽略這些警告，但您可以透過讓 Gitea 重新建立這些表來停止這些警告，使用以下命令：

gitea doctor recreate-table user

這將導致 Gitea 重新建立使用者表並將舊資料複製到新表中， 並正確設定預設值。

您可以使用以下命令要求 Gitea 重新建立多個表：

gitea doctor recreate-table table1 table2 ...

如果您希望 Gitea 重新建立所有表，請使用以下命令：

gitea doctor recreate-table

在運行這些命令之前，強烈建議您備份資料庫。

為什麼查看文件時製表符/縮進顯示錯誤​

如果您正在使用 Cloudflare，請在儀表板中關閉自動縮小選項。

Speed -> Optimization -> 在 Auto-Minify 設定中取消選中 HTML。

如何從磁盤採用儲存庫​

  • 將您的（裸）儲存庫添加到正確的位置，即您的設定所在的地方（repository.ROOT），確保它們位於正確的佈局<REPO_ROOT>/[user]/[repo].git。
    • **注意：**目錄名必須為小寫。
    • 您還可以在<ROOT_URL>/admin/config中檢查儲存庫根路徑。
  • 確保存在要採用儲存庫的使用者/組織。
  • 作為管理員，轉到<ROOT_URL>/admin/repos/unadopted並搜索。
  • 使用者也可以透過設定ALLOW_ADOPTION_OF_UNADOPTED_REPOSITORIES 獲得類似的權限。
  • 如果上述步驟都正確執行，您應該能夠選擇要採用的儲存庫。
    • 如果沒有找到儲存庫，請啟用調試日誌記錄以檢查是否有特定錯誤。