Merge branch 'main' into audit

2026-11-08 19:10:32 +00:00 · 2026-09-19 00:12:43 +00:00 · 2026-09-19 00:04:45 +00:00 · 2026-09-18 03:37:34 +00:00 · 2026-09-18 03:14:54 +02:00 · 2026-09-17 20:22:15 +00:00
1890 changed files with 8192 additions and 125967 deletions
@@ -8,7 +8,7 @@ on:
 jobs:
  build-docs:
-    runs-on: ubuntu-26.04
+    runs-on: ubuntu-24.04
    env:
      NODE_OPTIONS: --max-old-space-size=8192
      # search only appears once the credentials are set, the build falls back
@@ -19,13 +19,13 @@ jobs:
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
-      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
-          node-version: 26
+          node-version: 24
          cache: pnpm
      - name: prepare awesome list
        run: |
-          make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22 prepare-awesome-v28
+          make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
@@ -16,13 +16,13 @@ jobs:
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
-      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
-          node-version: 26
+          node-version: 24
          cache: pnpm
      - name: prepare awesome list
        run: |
-          make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22 prepare-awesome-v28
+          make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22
      - name: install dependencies
        run: pnpm install --frozen-lockfile
@@ -45,7 +45,7 @@ jobs:
          # pull requests from forks do not get the secrets, the build above is
          # then the only check and the preview is silently skipped
          if [ -z "${CLOUDFLARE_API_TOKEN:-}" ] || [ -z "${CLOUDFLARE_ACCOUNT_ID:-}" ]; then
-            echo "::notice::no Cloudflare credentials available (pull request from a fork?), skipping the preview deployment"
+            echo "no Cloudflare credentials available, skipping the preview deployment"
            exit 0
          fi
@@ -2,7 +2,7 @@ name: update api spec files
 on:
  schedule:
-    - cron: '0 3 * * 1' # every Monday at 03:00
+    - cron:  '0 */12 * * *' # every 12 hours on the hour
  workflow_dispatch:
 env:
@@ -6,6 +6,7 @@ sites/*/dist
 sites/*/.astro
 sites/*/.cache
 build/
 .docusaurus/
 # Misc
 .DS_Store
@@ -12,30 +12,20 @@ create_dir:
 clone_awesome: create_dir
 	git clone --branch=$(GITEA_AWESOME_BRANCH) $(GITEA_AWESOME_REMOTE) .tmp/upstream-awesome || true
 # the contributing guide moved to the gitea repository, the readme of
 # awesome-gitea still links to it with a relative path
 AWESOME_CONTRIBUTING_URL := https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md
 FIX_AWESOME_LINKS := sed 's|](contributing.md)|]($(AWESOME_CONTRIBUTING_URL))|'
 .PHONY: prepare-awesome-latest
 prepare-awesome-latest: clone_awesome
-	$(FIX_AWESOME_LINKS) .tmp/upstream-awesome/README.md > docs/awesome.md
+	cp .tmp/upstream-awesome/README.md docs/awesome.md
 .PHONY: prepare-awesome\#%
 prepare-awesome\#%:
-	$(FIX_AWESOME_LINKS) .tmp/upstream-awesome/README.md > versioned_docs/version-1.$*/awesome.md
+	cp .tmp/upstream-awesome/README.md  versioned_docs/version-1.$*/awesome.md
 # versions numbered without the 1. prefix, like 28
 .PHONY: prepare-awesome-v%
 prepare-awesome-v%:
 	$(FIX_AWESOME_LINKS) .tmp/upstream-awesome/README.md > versioned_docs/version-$*/awesome.md
 .PHONY: install
 install:
 	pnpm install
 .PHONY: prepare-docs
-prepare-docs: install prepare-awesome-latest prepare-awesome\#22 prepare-awesome\#23 prepare-awesome\#24 prepare-awesome\#25 prepare-awesome\#26 prepare-awesome\#27 prepare-awesome-v28
+prepare-docs: install prepare-awesome-latest prepare-awesome\#22 prepare-awesome\#23 prepare-awesome\#24 prepare-awesome\#25 prepare-awesome\#26 prepare-awesome\#27
 .PHONY: build
 build:
@@ -92,7 +82,7 @@ update-runner-docs:
 update-runner-docs-released:
 	./update_runner_docs.sh --released
-# freezes the current docs, runner or cli tree as a new version, see
+# freezes the current docs or runner tree as a new version, see
 # scripts/cut-version.mjs
 .PHONY: cut-version
 cut-version:
@@ -3,14 +3,13 @@
 The sources of [docs.gitea.com](https://docs.gitea.com), built with
 [Astro](https://astro.build) and [Starlight](https://starlight.astro.build).
-The site covers four products, all served from this repository:
+The site covers three products, all served from this repository:
 | Product | Content | Versions | Languages |
 | --- | --- | --- | --- |
-| Docs | `docs/`, `versioned_docs/`, `i18n/` | next, 28, 1.27 … 1.22 | English, 简体中文, 繁體中文 |
+| Docs | `docs/`, `versioned_docs/`, `i18n/` | next, 1.27 … 1.22 | English, 简体中文, 繁體中文 |
-| API | `static/swagger-*.json`, `static/openapi3-*.json` | next, 28, 1.27 … 1.22 | English |
+| API | `static/swagger-*.json`, `static/openapi3-*.json` | next, 1.27 … 1.22 | English |
-| Runner | `runner-docs/`, `runner-docs_versioned_docs/` | develop, 5 … 0 | English |
+| Runner | `runner-docs/`, `runner-docs_versioned_docs/` | develop, 3 … 0 | English |
 | CLI | `cli-docs/`, `cli-docs_versioned_docs/` | develop | English |
 The enterprise documentation is built and deployed from its own repository and
 reached through `/enterprise/`, which a Cloudflare worker maintained elsewhere
@@ -53,8 +52,7 @@ group from the `_category_.json` of its directory.
 ```shell
 make cut-version PRODUCT=docs VERSION=1.28
-make cut-version PRODUCT=runner VERSION=6
+make cut-version PRODUCT=runner VERSION=4
 make cut-version PRODUCT=cli VERSION=0.1
 ```
 This freezes the current tree, its translations and its sidebar. The label of
@@ -81,7 +79,7 @@ make update-api-docs-latest  # refresh only the documents of gitea main
 ```
 The documents of gitea main are refreshed automatically: the `update api spec
-files` workflow runs weekly and opens a pull request whenever gitea main
+files` workflow runs every 12 hours and opens a pull request whenever gitea main
 changed. Released versions are updated by hand when a new gitea version is
 documented.
@@ -90,8 +88,8 @@ documented.
 | Version | Content | URL |
 | --- | --- | --- |
 | develop | `runner-docs/` | `/runner/develop/` |
-| current series | `runner-docs_versioned_docs/version-5/` | `/runner/` |
+| current series | `runner-docs_versioned_docs/version-3/` | `/runner/` |
-| older series | `runner-docs_versioned_docs/version-4/` | `/runner/4/` |
+| older series | `runner-docs_versioned_docs/version-2/` | `/runner/2/` |
 A version directory covers a whole release series (`version-3` documents every
 `3.x` release), so a patch release only needs a content update, not a new
@@ -103,8 +101,7 @@ Its sidebar is written by hand: `runner-sidebars.js` for develop, and
 version.
 The pages under `reference/` are generated from the runner sources — the command
-line reference from `--help`, the example configuration from `config generate`
+line reference from `--help`, the example configuration from `generate-config`:
 (`generate-config` before 3.1):
 ```shell
 make update-runner-docs           # develop docs, from the main branch of gitea/runner
@@ -117,16 +114,6 @@ workflow runs weekly and opens a pull request whenever the runner's CLI or
 example configuration changed. Generating them needs Go, since the script builds
 the runner binary.
 ## CLI docs
 The documentation of `gt`, the Gitea CLI from
 [gitea/cli](https://gitea.com/gitea/cli), is laid out like the runner docs, with
 its sidebar in `cli-sidebars.js`. No series is documented yet, so `cli-docs/` is
 served at `/cli/`. Once a release exists, cut its series and list it in
 `cliSeries` in `packages/content-loader/src/products.ts`, which moves the develop
 docs to `/cli/develop/`. The guides leave the flags of each command to
 `gt <command> --help`.
 ## Deployment
 `main` is built and published by the `Build and Publish Docs site` workflow, to
@@ -1,55 +0,0 @@
 ---
 sidebar_position: 3
 ---
 # Logging in
 On a terminal, `gt auth login` asks for the instance and how to log in. gt never asks for
 your password.
 ## OAuth in a browser
 ```bash
 gt auth login --host https://gitea.example.com --oauth
 ```
 gt opens the instance's authorization page, so single sign-on and two-factor
 authentication work as on the web. The browser has to run on the same machine as gt.
 `--scopes` limits the token to fewer [scopes](/development/oauth2-provider#scopes); gt
 refreshes OAuth tokens on its own.
 ## Access token
 Create a token under **Settings > Applications** on the instance and pass it on stdin:
 ```bash
 gt auth login --host https://gitea.example.com --with-token < token.txt
 ```
 The token needs `read:user`, and the scopes of what you do with gt, such as
 `write:repository` and `write:issue` for working on pull requests.
 ## SSH key
 gt can sign its requests with an SSH key registered for your account instead of using a
 token:
 ```bash
 gt auth login --host https://gitea.example.com --ssh-key ~/.ssh/id_ed25519
 ```
 ## Accounts
 Tokens go to the system keyring, or with `--credential-store file` to gt's configuration
 directory on machines without one. Run `gt auth login` once per instance and account.
 gt picks the instance from the repository's remote or `--host`, and the account with
 `gt auth switch` or `--user`. `gt auth status` lists your accounts and `gt auth logout`
 removes one.
 For instances behind an access proxy, `--header` and `--client-cert` add headers and a
 client certificate.
 ## Git over HTTPS
 `gt auth setup-git` lets `git push` and `git fetch` over HTTPS use gt's login. gt's own
 clone and checkout commands need no setup.
@@ -1,40 +0,0 @@
 ---
 sidebar_position: 4
 ---
 # Using gt in CI
 Give gt a token and an instance through the environment, and turn prompts off:
 | Variable | Description |
 | --- | --- |
 | `GITEA_TOKEN` | Access token; gt never stores it |
 | `GITEA_CLI_HOST` or `GITEA_INSTANCE_URL` | URL of the instance |
 | `GITEA_CLI_REPO` | Repository, like `--repo` |
 `--no-input` makes a command fail instead of prompting, and `--yes` confirms changes in
 advance.
 ## Gitea Actions
 Gitea does not allow secret names that start with `GITEA_`, so store the token as, for
 example, `GT_TOKEN`:
 ```yaml
 on:
  push:
    branches: [main]
 jobs:
  staging:
    runs-on: ubuntu-latest
    env:
      GITEA_TOKEN: ${{ secrets.GT_TOKEN }}
      GITEA_CLI_HOST: ${{ gitea.server_url }}
      GITEA_CLI_REPO: ${{ gitea.repository }}
    steps:
      - run: curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh
      - run: gt workflow run deploy.yml --ref main --field env=staging --no-input
 ```
 `gt run watch` and `gt pr checks --watch` wait for runs and checks and fail when one fails.
@@ -1,38 +0,0 @@
 ---
 sidebar_position: 1
 slug: /
 ---
 # Gitea CLI
 [gt](https://gitea.com/gitea/cli) is the official command line client for Gitea. It works
 with repositories, issues, pull requests, releases, Actions and the other resources of a
 Gitea instance, from a terminal or a script.
 :::info Development version
 These pages describe builds from the `main` branch, published as `nightly` binaries and images.
 :::
 gt needs Gitea 28 or later, and Git for the commands that clone, check out or push.
 ## Getting started
 1. [Install gt](installation.md).
 2. [Log in](authentication.md):
   ```bash
   gt auth login
   ```
 3. Run commands in a clone of a repository on that instance, or select one with `--repo`:
   ```bash
   gt issue list --label bug
   gt pr checkout 13
   gt issue view 42 --repo gitea.com/gitea/cli
   ```
 `gt doctor` checks your setup and suggests a fix for each problem it finds.
 `gt <command> --help` lists the flags of a command, and `gt help environment` the global
 flags and environment variables.
@@ -1,37 +0,0 @@
 ---
 sidebar_position: 2
 ---
 # Installation
 gt is a single binary for Linux, macOS, Windows and FreeBSD.
 ## Install script
 The install script downloads gt from [dl.gitea.com](https://dl.gitea.com/gitea-cli/),
 verifies its checksum and installs it.
 ```bash
 # Linux, macOS, FreeBSD
 curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh
 ```
 ```powershell
 # Windows
 irm https://gitea.com/gitea/cli/raw/branch/main/scripts/install.ps1 | iex
 ```
 Set `GITEA_CLI_VERSION` to install a specific version, or `nightly` for the latest build
 of `main`.
 ## Other ways
 - **Binaries:** download them from [dl.gitea.com/gitea-cli](https://dl.gitea.com/gitea-cli/).
 - **Docker:** the [`gitea/gitea-cli`](https://hub.docker.com/r/gitea/gitea-cli) image runs
  `gt` as its entry point.
 - **Go:** `go install gitea.dev/cli/cmd/gt@latest`
 ## Shell completion and man pages
 `gt completion <shell>` prints the completion script for bash, zsh, fish or PowerShell;
 `gt completion <shell> --help` shows how to load it. `gt man` prints the manual.
@@ -1,22 +0,0 @@
 ---
 sidebar_position: 5
 ---
 # Output and scripting
 Scripts should read JSON: the text output is meant for people and may change.
 ```bash
 gt pr view 123 --json number,title,state
 gt issue list --json number,title --jq '.[] | "\(.number)\t\(.title)"'
 ```
 `--json` prints all fields or the ones you list; the **JSON FIELDS** section of a command's
 `--help` names them. `--jq` filters the result without needing jq installed. Piped lists
 print as tab-separated values.
 gt exits with 0 on success, 1 when a command fails, 2 on a usage error and 4 when
 authentication is missing or rejected; `gt help exit-codes` lists all codes.
 `gt api` calls any API endpoint with gt's login, and `gt alias set` defines shortcuts for
 commands you use often.
@@ -1 +0,0 @@
 []
@@ -1,16 +0,0 @@
 // Sidebar of the gt (Gitea CLI) documentation (develop version).
 // Released versions carry their own copy in
 // cli-docs_versioned_sidebars/version-<version>-sidebars.json.
 module.exports = {
  cli: [
    {
      type: 'doc',
      id: 'index',
      label: 'What is gt?',
    },
    'installation',
    'authentication',
    'ci',
    'scripting',
  ],
 };
@@ -2,8 +2,8 @@
 # is copied into the build output by the publish workflow, so that it is not
 # uploaded to S3/CloudFront where it would be publicly readable at /_headers.
 #
-# The build emits a single content hashed asset directory shared by every
+# Unlike the docusaurus build, astro emits a single content hashed asset
-# language, so no per locale rules are needed.
+# directory shared by every language, so no per locale rules are needed.
 # Content hashed build output (js, css, fonts). The file name changes with the
 # content, so these can be cached forever.
@@ -1,19 +1,17 @@
 # Redirects for legacy URLs and routes the site no longer serves directly.
-# The api reference, the runner and the cli docs are separate products,
+# The api reference and the runner docs are separate products, published in
-# published in english only, so they have no localized copy.
+# english only. Docusaurus served an empty localized copy of them.
 /zh-cn/api/* /api/:splat 301
 /zh-tw/api/* /api/:splat 301
 /zh-cn/runner/* /runner/:splat 301
 /zh-tw/runner/* /runner/:splat 301
 /zh-cn/cli/* /cli/:splat 301
 /zh-tw/cli/* /cli/:splat 301
 # The version served at the root of a product is also reachable under its
 # number, which is what the release notes and old links use.
-/api/28/* /api/:splat 301
+/api/1.27/* /api/:splat 301
 /runner/3/* /runner/:splat 301
-/28/* /:splat 301
+/1.27/* /:splat 301
 # The local search plugin had a results page of its own, algolia docsearch is a
 # modal opened from any page.
@@ -7,7 +7,6 @@
    "https://docs.gitea.com/zh-cn/",
    "https://docs.gitea.com/zh-tw/",
    "https://docs.gitea.com/runner/",
    "https://docs.gitea.com/cli/",
    "https://docs.gitea.com/api/",
    "https://docs.gitea.com/enterprise/"
  ],
@@ -16,8 +15,7 @@
    "https://docs.gitea.com/1.2*/**",
    "https://docs.gitea.com/*/1.2*/**",
    "https://docs.gitea.com/api/1.2*/**",
-    "https://docs.gitea.com/runner/[0-9]/**",
+    "https://docs.gitea.com/runner/[0-9]/**"
    "https://docs.gitea.com/cli/[0-9]*/**"
  ],
  "selectors": {
    "lvl0": { "selector": "//nav[contains(@aria-labelledby,'starlight__sidebar')]//a[@aria-current='page']/ancestor::details//summary//span", "type": "xpath", "global": true, "default_value": "Documentation" },
@@ -94,16 +94,16 @@ Most web and API requests pick up the signed-in user automatically.
 Other entry points record a system actor:
- `gitea:cli` for `gitea admin` commands and the `system:startup` and
+- `(gitea-cli)` for `gitea admin` commands and the `system:startup` and
  `system:shutdown` events
- `gitea:auth-source` for authentication-source syncs and for users an
+- `(gitea-auth-source)` for authentication-source syncs and for users an
  authentication source creates or updates at sign-in
 - `gitea-actions` for Gitea Actions tasks
- `gitea:deploy-key` for pushes with a deploy key
+- `(deploy-key)` for pushes with a deploy key
 - `(Cron)` for scheduled cron tasks
 - `Unknown` when no actor can be resolved
-Events of the `gitea:cli` actor use origin `cli`. Cron tasks, git hooks and
+Events of the `(gitea-cli)` actor use origin `cli`. Cron tasks, git hooks and
 other background work use origin `system`.
 ## What is recorded
@@ -337,13 +337,9 @@ The default login user email is `X-WEBAUTH-EMAIL`, you can change it via changin
 If set `ENABLE_REVERSE_PROXY_FULL_NAME=true`, a user full name expected in `X-WEBAUTH-FULLNAME` will be assigned to the user when auto creating the user. You can also change the header name with `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`.
-It applies to the web interface, Git over HTTP, Git LFS and the package registry.
+You can also limit the reverse proxy's IP address range with `REVERSE_PROXY_TRUSTED_PROXIES` which default value is `127.0.0.0/8,::1/128`. By `REVERSE_PROXY_LIMIT`, you can limit trusted proxies level.
-:::warning
+You can enable the this authentication method for the API with
 Gitea trusts these headers on every request it receives. Make sure Gitea is only reachable through your authenticating proxy, and that the proxy sets or removes these headers on every request, including on paths you exempt from authentication, for example for Git or package clients. `REVERSE_PROXY_TRUSTED_PROXIES` does not restrict them.
 :::
 To also accept them on the REST API under `/api/v1`, enable:
 ```ini
 [service]
@@ -83,7 +83,7 @@ cd gitea-dump-1610949662
 mv app.ini /etc/gitea/conf/app.ini
 mv data/* /var/lib/gitea/data/
 mv log/* /var/lib/gitea/log/
-mv repos/* /var/lib/gitea/data/gitea-repositories/
+mv repos/* /var/lib/gitea/data/repositories/
 chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea
 # mysql
@@ -130,8 +130,8 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build
   HTTP protocol.
 - `USE_COMPAT_SSH_URI`: **false**: Force ssh:// clone url instead of scp-style uri when
   default SSH port is used.
- `GO_GET_CLONE_URL_PROTOCOL`: **_empty_**: Scheme of the returned URL for the "go get" response.
+- `GO_GET_CLONE_URL_PROTOCOL`: **https**: Value for the "go get" request returns the repository url as https or ssh
-   Default is "https" if DISABLE_HTTP_GIT=false or SSH is disabled, otherwise "ssh".
+   default is https.
 - `ACCESS_CONTROL_ALLOW_ORIGIN`: **_empty_**: Value for Access-Control-Allow-Origin header,
   default is not to present.
@@ -179,7 +179,7 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build
 - `POPULATE_SQUASH_COMMENT_WITH_COMMIT_MESSAGES`: **false**: In default squash-merge messages include the commit message of all commits comprising the pull request.
 - `ADD_CO_COMMITTER_TRAILERS`: **true**: Add co-authored-by and co-committed-by trailers to merge commit messages if committer does not match author.
 - `RETARGET_CHILDREN_ON_MERGE`: **true**: Retarget child pull requests to the parent pull request branch target on merge of parent pull request. It only works on merged PRs where the head and base branch target the same repo.
- `DEFAULT_DELETE_BRANCH_AFTER_MERGE`: **true**: Set the default value for "Delete pull request branch after merge by default" for new repositories.
+- `DEFAULT_DELETE_BRANCH_AFTER_MERGE`: **false**: Set the default value for "Delete pull request branch after merge by default" for new repositories.
 - `DEFAULT_TITLE_SOURCE`: **auto**: Default source for the pull request title when opening a new PR. Valid options:
  - `first-commit`: Uses the oldest commit's summary as the title. If there are multiple commits, still uses the first commit's message.
  - `auto`: Uses the commit's summary when the PR contains a single commit; when there are multiple commits, converts the branch name into a human-readable title by normalizing separators and casing.
@@ -270,10 +270,9 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `FOLDER_ICON_THEME`: **basic**: The icon theme for folders (basic/material).
 - `MAX_DISPLAY_FILE_SIZE`: **8388608**: Max size of files to be displayed (default is 8MiB)
 - `AMBIGUOUS_UNICODE_DETECTION`: **true**: Detect ambiguous unicode characters in file contents and show warnings on the UI
- `REACTIONS`: All available reactions users can choose on issues, pull requests and comments.
+- `REACTIONS`: All available reactions users can choose on issues/prs and comments
    Values can be emoji alias (:smile:) or a unicode emoji.
    For custom reactions, add a tightly cropped square image to public/assets/img/emoji/reaction_name.png
 - `RELEASE_REACTIONS`: **+1, laugh, hooray, heart, rocket, eyes**: Reactions available for releases, in the same format as `REACTIONS`.
 - `REACTION_MAX_USER_NUM`: **10**: Change the number of users that are displayed in reactions tooltip (triggered by mouse hover).
 - `CUSTOM_EMOJIS`: **gitea, codeberg, gitlab, git, github, gogs**: Additional Emojis not defined in the utf8 standard.
    By default, we support Gitea (:gitea:), to add more copy them to public/assets/img/emoji/emoji_name.png and
@@ -349,7 +348,8 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `PROXY_PROTOCOL_TLS_BRIDGING`: **false**: When protocol is https, expect PROXY protocol headers after TLS negotiation.
 - `PROXY_PROTOCOL_HEADER_TIMEOUT`: **5s**: Timeout to wait for PROXY protocol header (set to 0 to have no timeout)
 - `PROXY_PROTOCOL_ACCEPT_UNKNOWN`: **false**: Accept PROXY protocol headers with Unknown type.
- `ROOT_URL`: **`{PROTOCOL}://localhost:{HTTP_PORT}/`**:
+- `DOMAIN`: **localhost**: Domain name of this server.
 - `ROOT_URL`: **`{PROTOCOL}://{DOMAIN}:{HTTP_PORT}/`**:
   Overwrite the automatically generated public URL.
   This is useful if the internal and the external URL don't match (e.g. behind a reverse proxy).
 - `PUBLIC_URL_DETECTION`: **`auto`**: Controls how to generate the public URL. Most instances should use the "auto" behavior,
@@ -404,7 +404,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
  If it is set to `(DOER_USERNAME)`, it will use current signed-in user's username.
  This option is only for some advanced users who have configured their SSH reverse-proxy and need to use different usernames for git SSH clone.
  Most users should just leave it blank and/or modify the `BUILTIN_SSH_SERVER_USER`.
- `SSH_DOMAIN`: **_empty_**: Domain name to be exposed in clone URL, defaults to the domain part of ROOT_URL
+- `SSH_DOMAIN`: **`{DOMAIN}`**: Domain name of this server, used for displayed clone URL.
 - `SSH_PORT`: **22**: SSH port displayed in clone URL. If you need a different "SSH clone port" from the real "SSH listen port", set the SSH_LISTEN_PORT separately.
 - `SSH_LISTEN_HOST`: **0.0.0.0**: Listen address for the built-in SSH server.
 - `SSH_LISTEN_PORT`: **`{SSH_PORT}`**: Port for the built-in SSH server.
@@ -420,7 +420,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `SSH_SERVER_CIPHERS`: **`chacha20-poly1305@openssh.com`, `aes128-ctr`, `aes192-ctr`, `aes256-ctr`, `aes128-gcm@openssh.com`, `aes256-gcm@openssh.com`**: For the built-in SSH server, choose the ciphers to support for SSH connections, for system SSH this setting has no effect.
 - `SSH_SERVER_KEY_EXCHANGES`: **curve25519-sha256, ecdh-sha2-nistp256, ecdh-sha2-nistp384, ecdh-sha2-nistp521, diffie-hellman-group14-sha256, diffie-hellman-group14-sha1**: For the built-in SSH server, choose the key exchange algorithms to support for SSH connections, for system SSH this setting has no effect.
 - `SSH_SERVER_MACS`: **`hmac-sha2-256-etm@openssh.com`, `hmac-sha2-256`, `hmac-sha1`**: For the built-in SSH server, choose the MACs to support for SSH connections, for system SSH this setting has no effect
- `SSH_SERVER_HOST_KEYS`: **ssh/gitea.rsa, ssh/gitea.ed25519, ssh/gitea.ecdsa, ssh/gogs.rsa**: For the built-in SSH server, choose the keypairs to offer as the host key. The private key should be at `SSH_SERVER_HOST_KEY` and the public `SSH_SERVER_HOST_KEY.pub`. Relative paths are made absolute relative to the `APP_DATA_PATH`. If none of the keys exist, a 4096 bit RSA, a 256 bit ECDSA and an ED25519 key will be created for you.
+- `SSH_SERVER_HOST_KEYS`: **ssh/gitea.rsa, ssh/gogs.rsa**: For the built-in SSH server, choose the keypairs to offer as the host key. The private key should be at `SSH_SERVER_HOST_KEY` and the public `SSH_SERVER_HOST_KEY.pub`. Relative paths are made absolute relative to the `APP_DATA_PATH`. If no key exists a 4096 bit RSA key will be created for you.
 - `SSH_KEY_TEST_PATH`: **/tmp**: Directory to create temporary files in when testing public keys using ssh-keygen, default is the system temporary directory.
 - `SSH_KEYGEN_PATH`: **_empty_**: Use `ssh-keygen` to parse public SSH keys. The value is passed to the shell. By default, Gitea does the parsing itself.
 - `SSH_EXPOSE_ANONYMOUS`: **false**: Enable exposure of SSH clone URL to anonymous visitors, default is false.
@@ -587,7 +587,8 @@ And the following unique queues:
 - `SECRET_KEY`: **\<random at every install\>**: Global secret key. This key is VERY IMPORTANT, if you lost it, the data encrypted by it (like 2FA secret) can't be decrypted anymore.
 - `SECRET_KEY_URI`: **_empty_**: Instead of defining SECRET_KEY, this option can be used to use the key stored in a file (example value: `file:/etc/gitea/secret_key`). It shouldn't be lost like SECRET_KEY.
 - `LOGIN_REMEMBER_DAYS`: **31**: How long to remember that a user is logged in before requiring relogin (in days).
- `COOKIE_REMEMBER_NAME`: **gitea\_remember**: Name of cookie used to store authentication information.
+- `COOKIE_REMEMBER_NAME`: **gitea\_incredible**: Name of cookie used to store authentication
   information.
 - `REVERSE_PROXY_LOGOUT_REDIRECT`: **_empty_**: URL or relative path to redirect users to after logout when authentication is handled by a reverse proxy or SSO. For example: `/my-sso/logout?return=/my-sso/home`.
 - `REVERSE_PROXY_AUTHENTICATION_USER`: **X-WEBAUTH-USER**: Header name for reverse proxy
   authentication.
@@ -595,8 +596,7 @@ And the following unique queues:
   authentication provided email.
 - `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`: **X-WEBAUTH-FULLNAME**: Header name for reverse proxy
   authentication provided full name.
- `REVERSE_PROXY_LIMIT`: **1**: Interpret the X-Real-IP, X-Forwarded-For or Forwarded header, in that order, and set this as the remote IP for the request.
+- `REVERSE_PROXY_LIMIT`: **1**: Interpret X-Forwarded-For header or the X-Real-IP header and set this as the remote IP for the request.
   The client port is taken from the header value or, with X-Real-IP, from X-Real-Port.
   Number of trusted proxy count. Set to zero to not use these headers.
 - `REVERSE_PROXY_TRUSTED_PROXIES`: **127.0.0.0/8,::1/128**: List of IP addresses and networks separated by comma of trusted proxy servers. Use `*` to trust all.
 - `X_FRAME_OPTIONS`: **SAMEORIGIN**: Set the `X-Frame-Options` header value for all HTTP responses. Set to `unset` to not send the header. Previously located in `[cors]`.
@@ -647,25 +647,14 @@ And the following unique queues:
 - `SUCCESSFUL_TOKENS_CACHE_SIZE`: **20**: Cache successful token hashes. API tokens are stored in the DB as pbkdf2 hashes however, this means that there is a potentially significant hashing load when there are multiple API operations. This cache will store the successfully hashed tokens in a LRU cache as a balance between performance and security.
 - `DISABLE_QUERY_AUTH_TOKEN`: **false**: Reject API tokens sent in URL query string (Accept Header-based API tokens only). This setting will default to `true` in Gitea 1.23 and be deprecated in Gitea 1.24.
 - `TWO_FACTOR_AUTH`: **_empty_**: set to enforced to enforce two factor authentication. Only available in Gitea 1.24 and later.
- `EGRESS_MODE`: **lax**: Egress mode toggles between strictness of outgoing requests:
+- `ALLOWED_HOST_LIST`: **external**: Webhook and oauth2 clients can only call allowed hosts for security reasons. Comma separated list.
  - `lax` non-public targets (private, loopback, link-local, CGNAT and special-use ranges) to be allowed, it allows all public ones
  - `strict` requires an explicit allow of all addresses
 - `ALLOWED_HOST_LIST`: **_empty_**: Webhook and oauth2 clients can only call allowed hosts for security reasons. Comma separated list, eg: `192.168.1.0/24:3000`, `[2001:db8::/32]:9090`, `*.mydomain.com:[80|443]`
  - Built-in networks:
    - `loopback`: 127.0.0.0/8 for IPv4 and ::1/128 for IPv6, localhost is included.
-    - `private`: RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), RFC 4193 (FC00::/7) and RFC 6598 CGNAT (100.64.0.0/10). Also called LAN/Intranet.
+    - `private`: RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) and RFC 4193 (FC00::/7). Also called LAN/Intranet.
-  - CIDR list: `1.2.3.0/8`, `2001:db8::/32`, and with a port `[2001:db8::/32]:9090` (IPv6 addresses and CIDRs need brackets when a port is given)
+    - `external`: A valid non-private unicast IP, you can access all hosts on public internet.
-  - Host matching: `example.com` matches the host and any subdomain, dot-anchored so `notexample.com` never matches. `*.example.com` and `.example.com` match only subdomains, the apex itself is excluded. IDN names must be given as punycode.
+    - `*`: All hosts are allowed.
-  - All addresses can have ports specified. Accepted port specs:
+  - CIDR list: `1.2.3.0/8` for IPv4 and `2001:db8::/32` for IPv6
-    - a single port: `192.168.1.0/24:3000`
+  - Wildcard hosts: `*.mydomain.com`, `192.168.100.*`
    - a range, both bounds inclusive: `*.mydomain.com:3000-3010`
    - a bracketed set of ports and ranges, `|` separated: `*.mydomain.com:[80|443|3000-3010]`
    - all ports: `*.mydomain.com:*`
  - A portless entry covers all ports in `lax` mode, only 80 and 443 in `strict` mode
  - Port specs apply only where the list is consulted: in `lax` mode that is non-public targets alone, public targets are allowed on every port whatever the list says. In `strict` mode every target is checked, so ports restrict public hosts too.
  - Non-public targets need an IP or built-in entry, a host name entry alone never covers them.
  - Reserved addresses (the IPv4-embedding NAT64, Teredo and 6to4 ranges, this-network, multicast and broadcast) are denied whatever the list says. To reach them configure an HTTP proxy
  - This list is enforced on direct connections only. When an HTTP proxy is configured, restricting the proxied target is the proxy server's responsibility.
 ## Audit (`audit`)
@@ -681,8 +670,8 @@ And the following unique queues:
 ## OpenID (`openid`)
- `ENABLE_OPENID_SIGNIN`: **false**: Allow authentication in via OpenID.
+- `ENABLE_OPENID_SIGNIN`: **true**: Allow authentication in via OpenID.
- `ENABLE_OPENID_SIGNUP`: **false**: Allow registering via OpenID.
+- `ENABLE_OPENID_SIGNUP`: **! DISABLE\_REGISTRATION**: Allow registering via OpenID.
 - `WHITELISTED_URIS`: **_empty_**: If non-empty, list of POSIX regex patterns matching
   OpenID URI's to permit.
 - `BLACKLISTED_URIS`: **_empty_**: If non-empty, list of POSIX regex patterns matching
@@ -717,7 +706,7 @@ And the following unique queues:
   Requires `Mailer` to be enabled.
 - `REGISTER_MANUAL_CONFIRM`: **false**: Enable this to manually confirm new registrations.
   Requires `REGISTER_EMAIL_CONFIRM` to be disabled.
- `DISABLE_REGISTRATION`: **true**: Disable registration, after which only admin can create
+- `DISABLE_REGISTRATION`: **false**: Disable registration, after which only admin can create
   accounts for users.
 - `REQUIRE_EXTERNAL_REGISTRATION_PASSWORD`: **false**: Enable this to force externally created
   accounts (via GitHub, OpenID Connect, etc) to create a password.
@@ -741,8 +730,8 @@ And the following unique queues:
   If you set it to false, maybe it also needs to set `ENABLE_BASIC_AUTHENTICATION` to false to
   completely disable password-based authentication.
 - `ENABLE_PASSKEY_AUTHENTICATION`: **true**: Allow users to sign-in with a passkey
- `ENABLE_REVERSE_PROXY_AUTHENTICATION`: **false**: Enable reverse proxy authentication for the web interface, Git over HTTP, Git LFS and the package registry. Gitea must only be reachable through the proxy, see [Reverse Proxy](authentication.md#reverse-proxy).
+- `ENABLE_REVERSE_PROXY_AUTHENTICATION`: **false**: Enable this to allow reverse proxy authentication for web requests
- `ENABLE_REVERSE_PROXY_AUTHENTICATION_API`: **false**: Enable reverse proxy authentication for the REST API under `/api/v1`.
+- `ENABLE_REVERSE_PROXY_AUTHENTICATION_API`: **false**: Enable this to allow reverse proxy authentication for API requests, the reverse proxy is responsible for ensuring that no CSRF is possible.
 - `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION`: **false**: Enable this to allow auto-registration
   for reverse authentication.
 - `ENABLE_REVERSE_PROXY_EMAIL`: **false**: Enable this to allow to auto-registration with a
@@ -776,7 +765,7 @@ And the following unique queues:
 - `DEFAULT_ALLOW_ONLY_CONTRIBUTORS_TO_TRACK_TIME`: **true**: Only allow users with write permissions to track time.
 - `EMAIL_DOMAIN_ALLOWLIST`: **_empty_**: If non-empty, comma separated list of domain names that can only be used to register on this instance, wildcard is supported.
 - `EMAIL_DOMAIN_BLOCKLIST`: **_empty_**: If non-empty, comma separated list of domain names that cannot be used to register on this instance, wildcard is supported.
- `SHOW_REGISTRATION_BUTTON`: **false**: Show Registration button, defaults to true only if both DISABLE_REGISTRATION and ALLOW_ONLY_EXTERNAL_REGISTRATION are false
+- `SHOW_REGISTRATION_BUTTON`: **! DISABLE\_REGISTRATION**: Show Registration Button
 - `SHOW_MILESTONES_DASHBOARD_PAGE`: **true** Enable this to show the milestones dashboard page - a view of all the user's milestones
 - `AUTO_WATCH_NEW_REPOS`: **true**: Enable this to let all organisation users watch new repos when they are created
 - `AUTO_WATCH_ON_CHANGES`: **false**: Enable this to make users watch a repository after their first commit to it
@@ -786,7 +775,8 @@ And the following unique queues:
 - `DEFAULT_ORG_MEMBER_VISIBLE`: **false** True will make the membership of the users visible when added to the organisation.
 - `ALLOW_ONLY_INTERNAL_REGISTRATION`: **false** Set to true to force registration only via Gitea.
 - `ALLOW_ONLY_EXTERNAL_REGISTRATION`: **false** Set to true to force registration only using third-party services.
- `NO_REPLY_ADDRESS`: **_empty_**: Value for the domain part of the user's email address in the git log if user has set KeepEmailPrivate to true. The user's email will be replaced with a concatenation of the user name in lower case, "@" and NO_REPLY_ADDRESS. Default value is "noreply." + the domain part of ROOT_URL
+- `NO_REPLY_ADDRESS`: **noreply.DOMAIN** Value for the domain part of the user's email address in the Git log if user has set KeepEmailPrivate to true. DOMAIN resolves to the value in server.DOMAIN.
  The user's email will be replaced with a concatenation of the user name in lower case, "@" and NO_REPLY_ADDRESS.
 - `USER_DELETE_WITH_COMMENTS_MAX_TIME`: **0** Minimum amount of time a user must exist before comments are kept when the user is deleted.
 - `VALID_SITE_URL_SCHEMES`: **http, https**: Valid site url schemes for user profiles
@@ -819,11 +809,9 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type
 - `DELIVER_TIMEOUT`: **5**: Delivery timeout (sec) for shooting webhooks.
 - `SKIP_TLS_VERIFY`: **false**: Allow insecure certification.
 - `PAGING_NUM`: **10**: Number of webhook history events that are shown in one page.
- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https://, socks5://, blank will follow environment http_proxy/https_proxy. If not given, will use global proxy setting.
+- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https//, socks://, blank will follow environment http_proxy/https_proxy. If not given, will use global proxy setting.
 - `PROXY_HOSTS`: **_empty_`**: Comma separated list of host names requiring proxy. Glob patterns (*) are accepted; use ** to match all hosts. If not given, will use global proxy setting.
 When a proxy is configured, Gitea does not enforce `[security]` `ALLOWED_HOST_LIST` on the proxied target, the proxy server is expected to restrict it.
 ## Mailer (`mailer`)
 :::warning
@@ -898,27 +886,27 @@ In-Reply-To =
 ## Cache (`cache`)
- `ADAPTER`: **memory**: Either `memory`, `redis`, `memcache`, or `twoqueue`.
+- `ADAPTER`: **memory**: Cache engine adapter, either `memory`, `redis`, `twoqueue` or `memcache`. (`twoqueue` represents a size limited LRU cache.)
- `INTERVAL`: **60**: For `memory` and `twoqueue`, GC interval in seconds.
+- `INTERVAL`: **60**: Garbage Collection interval (sec), for memory and twoqueue cache only.
- `HOST`: **_empty_**: For `redis` and `memcache`, connection host address. For `twoqueue` sets configuration for the queue. If left empty while `ADAPTER` is `redis`, it falls back to [redis/CONN_STR](#redis-redis) when that is set.
+- `HOST`: **_empty_**: Connection string for `redis` and `memcache`. For `twoqueue` sets configuration for the queue. If left empty while `ADAPTER` is `redis`, it falls back to [redis/CONN_STR](#redis-redis) when that is set.
  - Redis: `redis://:[email protected]:6379/0?pool_size=100&idle_timeout=180s` (See [queue/CONN_STR](#queue-queue-and-queue) for information on additional supported connection types)
    - For a Redis cluster: `redis+cluster://:[email protected]:6379/0?pool_size=100&idle_timeout=180s`
    - For a Redis sentinel: `redis+sentinel://:macaron@sentinel0:26379,sentinel1:26379,sentinel2:26379/0?pool_size=100&idle_timeout=180s&master_name=mymaster`
-  - Memcache: `127.0.0.1:11211`
+  - Memcache: `127.0.0.1:9090;127.0.0.1:9091`
  - TwoQueue LRU cache: `{"size":50000,"recent_ratio":0.25,"ghost_ratio":0.5}` or `50000` representing the maximum number of objects stored in the cache.
- `ITEM_TTL`: **16h**: Time to keep items in cache if not used. Setting it to -1 disables caching.
+- `ITEM_TTL`: **16h**: Time to keep items in cache if not used, Setting it to -1 disables caching.
 ## Cache - LastCommitCache settings (`cache.last_commit`)
- `ITEM_TTL`: **8760h**: Time to keep items in cache if not used. Setting it to -1 disables caching.
+- `ITEM_TTL`: **8760h**: Time to keep items in cache if not used, Setting it to -1 disables caching.
 - `COMMITS_COUNT`: **1000**: Only enable the cache when repository's commits count great than.
 ## Session (`session`)
- `PROVIDER`: **file**: Either "memory", "file", "redis" or "db", default is "file". "db" will reuse the configuration in `[database]`
+- `PROVIDER`: **memory**: Session engine provider \[memory, file, redis, db, mysql, couchbase, memcache, postgres\]. Setting `db` will reuse the configuration in `[database]`
 - `PROVIDER_CONFIG`: **data/sessions**: For file, the root path; for db, empty (database config will be used); for others, the connection string. Relative paths will be made absolute against _`AppWorkPath`_. For the `redis` provider, if left empty it falls back to [redis/CONN_STR](#redis-redis) when that is set.
 - `COOKIE_SECURE`:**_empty_**: `true` or `false`. Enable this to force using HTTPS for all session access. If not set, it defaults to `true` if the ROOT_URL is an HTTPS URL.
- `COOKIE_NAME`: **gitea\_session**: Session cookie name
+- `COOKIE_NAME`: **i\_like\_gitea**: The name of the cookie used for the session ID.
 - `GC_INTERVAL_TIME`: **86400**: GC interval in seconds.
 - `SESSION_LIFE_TIME`: **86400**: Session life time in seconds, default is 86400 (1 day)
 - `DOMAIN`: **_empty_**: Sets the cookie Domain
@@ -945,7 +933,7 @@ In-Reply-To =
  - none = no avatar will be displayed
  - random = random avatar will be generated
  - image = default image will be used (which is set in `REPOSITORY_AVATAR_FALLBACK_IMAGE`)
- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **_empty_**: Image used as default repository avatar (if `REPOSITORY_AVATAR_FALLBACK` is set to image and none was uploaded). The value is used as-is, without prepending the sub-path of `ROOT_URL`. Empty uses Gitea's builtin repository avatar.
+- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **/img/repo_default.png**: Image used as default repository avatar (if `REPOSITORY_AVATAR_FALLBACK` is set to image and none was uploaded)
 ## Project (`project`)
@@ -1329,6 +1317,7 @@ These options are written into the gitconfig file under `[git] HOME_PATH` when G
 - `diff.algorithm`: **histogram**
 - `core.logAllRefUpdates`: **true**
 - `gc.reflogExpire`: **90**
 ## Metrics (`metrics`)
@@ -1356,7 +1345,7 @@ These options are written into the gitconfig file under `[git] HOME_PATH` when G
 - `JWT_SECRET_URI`: **_empty_**: Instead of defining JWT_SECRET in the configuration, this configuration option can be used to give Gitea a path to a file that contains the secret (example value: `file:/etc/gitea/oauth2_jwt_secret`)
 - `JWT_SIGNING_PRIVATE_KEY_FILE`: **jwt/private.pem**: Private key file path used to sign OAuth2 tokens. The path is relative to `APP_DATA_PATH`. This setting is only needed if `JWT_SIGNING_ALGORITHM` is set to `RS256`, `RS384`, `RS512`, `ES256`, `ES384` or `ES512`. The file must contain a RSA or ECDSA private key in the PKCS8 format. If no key exists a 4096 bit key will be created for you.
 - `MAX_TOKEN_LENGTH`: **32767**: Maximum length of token/cookie to accept from OAuth2 provider
- `DEFAULT_APPLICATIONS`: **git-credential-oauth, git-credential-manager, gitea-cli, gitea-app, gitea-vscode**: Pre-register OAuth applications for some services on startup. See the [OAuth2 documentation](/development/oauth2-provider.md) for the list of available options. `tea` is accepted as an alias of `gitea-cli`.
+- `DEFAULT_APPLICATIONS`: **git-credential-oauth, git-credential-manager, tea, gitea-app**: Pre-register OAuth applications for some services on startup. See the [OAuth2 documentation](/development/oauth2-provider.md) for the list of available options.
 - `CUSTOM_SCHEMES`: **_empty_**: By default, OAuth2 applications can only use "http" and "https" as their redirect URI schemes.
  If you need to use other schemes (e.g. for desktop applications), you can specify them here as a comma-separated list.
  For example: set "my-scheme, com.example.app" to support "my-scheme://..." and "com.example.app://..." redirect URIs.
@@ -1440,13 +1429,11 @@ in this mapping or the filetype using heuristics.
 - `MAX_ATTEMPTS`: **3**: Max attempts per http/https request on migrations.
 - `RETRY_BACKOFF`: **3**: Backoff time per http/https request retry (seconds)
- `EGRESS_MODE`: **lax**: Mode toggles between strictness of scanning outgoing requests, same format as `EGRESS_MODE` in [`security`](#security-security).
+- `ALLOWED_DOMAINS`: **_empty_**: Domains allowlist for migrating repositories, default is blank. It means external hosts will be allowed. Multiple domains could be separated by commas. Wildcard is supported: `github.com, *.github.com`.
- `ALLOWED_HOST_LIST`: **_empty_**: Hosts migrations and mirrors may call, same format as `ALLOWED_HOST_LIST` in [`security`](#security-security). Private, loopback and link-local addresses need a builtin or CIDR entry. When unset, the deprecated `ALLOWED_DOMAINS` entries apply on every port with `strict` as the default mode, and the deprecated `ALLOW_LOCALNETWORKS` adds `private, loopback`.
+- `BLOCKED_DOMAINS`: **_empty_**: Domains blocklist for migrating repositories, default is blank. Multiple domains could be separated by commas. When `ALLOWED_DOMAINS` is not blank, this option has a higher priority to deny domains. Wildcard is supported.
- `BLOCKED_HOST_LIST`: **_empty_**: Hosts migrations and mirrors may never call, portless entries cover all ports.
+- `ALLOW_LOCALNETWORKS`: **false**: Allow private addresses defined by RFC 1918, RFC 1122, RFC 4632 and RFC 4291. If a domain is allowed by `ALLOWED_DOMAINS`, this option will be ignored.
 - `SKIP_TLS_VERIFY`: **false**: Allow skip tls verify
 These lists are enforced on direct connections only. When a proxy is configured (`[proxy]`, `[git.config]` `http.proxy` or the environment), restricting the proxied target is the proxy server's responsibility.
 ## Federation (`federation`)
 - `ENABLED`: **false**: Enable/Disable federation capabilities
@@ -1488,9 +1475,8 @@ These lists are enforced on direct connections only. When a proxy is configured
 - `LIMIT_SIZE_RPM`: **-1**: Maximum size of a RPM upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_RUBYGEMS`: **-1**: Maximum size of a RubyGems upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_SWIFT`: **-1**: Maximum size of a Swift upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_TERRAFORM_MODULE`: **-1**: Maximum size of a Terraform module archive upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`). Archives are additionally capped at 32 MiB decompressed.
 - `LIMIT_SIZE_TERRAFORM_STATE`: **-1**: Maximum size of a Terraform state upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_VAGRANT`: **-1**: Maximum size of a Vagrant upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_TERRAFORM_STATE``: **-1**: Maximum size of a Terraform state upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 ## Mirror (`mirror`)
@@ -1682,16 +1668,14 @@ is `data/repo-archive` and the default of `MINIO_BASE_PATH` is `repo-archive/`.
 ## Proxy (`proxy`)
 - `PROXY_ENABLED`: **false**: Enable the proxy if true, all requests to external via HTTP will be affected, if false, no proxy will be used even environment http_proxy/https_proxy
- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https://, socks5://, blank will follow environment http_proxy/https_proxy
+- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https//, socks://, blank will follow environment http_proxy/https_proxy
 - `PROXY_HOSTS`: **_empty_**: Comma separated list of host names requiring proxy. Glob patterns (*) are accepted; use ** to match all hosts.
 When a proxy is configured, Gitea does not enforce the egress lists (`[security]`, `[migrations]`) on the proxied target, the proxy server is expected to restrict it.
 i.e.
 ```ini
 PROXY_ENABLED = true
-PROXY_URL = socks5://127.0.0.1:1080
+PROXY_URL = socks://127.0.0.1:1080
 PROXY_HOSTS = *.github.com
 ```
@@ -1709,8 +1693,7 @@ PROXY_HOSTS = *.github.com
  But it will save storage space and network bandwidth, so it's still recommended to use compression.
 - `ARTIFACT_RETENTION_DAYS`: **90**: Days to keep artifacts. Old artifacts will be deleted after this period. 0 means keep forever.
  Changes only apply to newly uploaded artifacts, existing ones keep the expiry stored when they were uploaded.
-  Workflows can request a shorter retention period, down to 1 day.
+  Artifacts could have their own retention periods by setting the `retention-days` option in `actions/upload-artifact` step.
 - `ARTIFACT_PREVIEW_MAX_SIZE`: **10485760**: Maximum total artifact size in bytes that can be browsed or previewed in the web UI. Set to `0` to disable artifact previews or `-1` for no limit. Individual files are also limited by [`MAX_DISPLAY_FILE_SIZE`](#ui-ui).
 - `RUN_RETENTION_DAYS`: **400**: Days to keep completed runs. Old runs and everything under them will be deleted after this period. 0 means keep forever.
 - `ZOMBIE_TASK_TIMEOUT`: **10m**: Timeout to stop the task which have running status, but haven't been updated for a long time
 - `ENDLESS_TASK_TIMEOUT`: **3h**: Timeout to stop the tasks which have running status and continuous updates, but don't end for a long time
@@ -1720,9 +1703,18 @@ PROXY_HOSTS = *.github.com
 - `SCOPED_WORKFLOW_DIRS`: **.gitea/scoped_workflows**: Comma-separated list of directories holding [scoped workflows](usage/actions/scoped-workflows.md) (workflows defined in a central source repository that run on other repositories). Must not overlap with `WORKFLOW_DIRS`. Leave empty so no directory is scanned for scoped workflows; none are found or run.
 - `MAX_RERUN_ATTEMPTS`: **50**: Maximum number of attempts a single workflow run can have (initial run + reruns). Defaults value is 50. Set any positive value that fits your workflow needs.
-`DEFAULT_ACTIONS_URL` sets where runners download actions without a host.
+`DEFAULT_ACTIONS_URL` indicates where the Gitea Actions runners should find the actions with relative path.
-With `github`, `uses: actions/checkout@v4` resolves to `https://github.com/actions/checkout@v4`, with `self` to `<ROOT_URL>/actions/checkout@v4`.
+For example, `uses: actions/checkout@v4` means `https://github.com/actions/checkout@v4` since the value of `DEFAULT_ACTIONS_URL` is `github`.
-`self` requires mirroring every action you use to your instance, so prefer naming the host per action instead: `uses: self:owner/repo@ref` for your instance, or a full URL like `uses: https://gitea.com/actions/checkout@v4` for any other host.
+And it can be changed to `self` to make it `root_url_of_your_gitea/actions/checkout@v4`.
 Please note that using `self` is not recommended for most cases, as it could make names globally ambiguous.
 Additionally, it requires you to mirror all the actions you need to your Gitea instance, which may not be worth it.
 Therefore, please use `self` only if you understand what you are doing.
 In earlier versions (`<= 1.19`), `DEFAULT_ACTIONS_URL` could be set to any custom URLs like `https://gitea.com` or `http://your-git-server,https://gitea.com`, and the default value was `https://gitea.com`.
 However, later updates removed those options, and now the only options are `github` and `self`, with the default value being `github`.
 However, if you want to use actions from other git server, you can use a complete URL in `uses` field, it's supported by Gitea (but not GitHub).
 Like `uses: https://gitea.com/actions/checkout@v4` or `uses: http://your-git-server/actions/checkout@v4`.
 ## Other (`other`)
@@ -16,7 +16,6 @@ aliases:
 4. Make sure `Host` and `X-Forwarded-Proto` headers are correctly passed to Gitea to make Gitea see the real URL being visited.
 5. Make sure your webserver has a certificate, including all intermediate and RootCA certificates, for `git clone` and `git pull` to work.
 6. Gitea uses a WebSocket connection at `/-/ws` for real-time updates like the notification counter. Make sure the reverse-proxy talks HTTP/1.1 and forwards the `Upgrade` and `Connection` headers, see the examples below. Without it, Gitea falls back to periodic polling.
 7. Make sure the reverse-proxy sets the `X-Real-IP` header, otherwise Gitea uses a client-sent value. For example `header_up X-Real-IP {remote_host}` in Caddy's `reverse_proxy`, `RequestHeader set X-Real-IP "expr=%{REMOTE_ADDR}"` in Apache or `http-request set-header X-Real-IP %[src]` in HAProxy. To log the client port, also set `X-Real-Port`, for example `proxy_set_header X-Real-Port $remote_port;` in nginx.
 ### Use a sub-path
@@ -73,7 +73,6 @@ By default, this creates a token with very limited permissions. To complete your
 - `activitypub`
 - `admin`
 - `commitstatus` (included in `repository`)
 - `issue`
 - `misc`
 - `notification`
@@ -111,9 +111,6 @@ Gitea token scopes are as follows:
 | **admin** | `/admin/*` API routes: Site-wide administrative operations (hidden for non-admin accounts).                                                          |
 | &nbsp;&nbsp;&nbsp; **read:admin** | Grants read access for admin operations, such as getting cron jobs or registered user emails.                                                        |
 | &nbsp;&nbsp;&nbsp; **write:admin** | Grants read/write/delete access for admin operations, such as running cron jobs or updating user accounts.                                           |
 | **commitstatus** | `/repos/{owner}/{repo}/statuses/{sha}` and `/repos/{owner}/{repo}/commits/{ref}/status(es)` API routes: Commit status operations.                        |
 | &nbsp;&nbsp;&nbsp; **read:commitstatus** | Grants read access to commit statuses. Included in `read:repository`.                                                                                |
 | &nbsp;&nbsp;&nbsp; **write:commitstatus** | Grants read/write access to commit statuses, such as reporting CI results. Included in `write:repository`.                                           |
 | **issue** | `issues/*`, `labels/*`, `milestones/*` API routes: Issue-related operations.                                                                         |
 | &nbsp;&nbsp;&nbsp; **read:issue** | Grants read access for issues operations, such as getting issue comments, issue attachments, and milestones.                                         |
 | &nbsp;&nbsp;&nbsp; **write:issue** | Grants read/write/delete access for issues operations, such as posting or editing an issue comment or attachment, and updating milestones.           |
@@ -144,9 +141,7 @@ Gitea creates OAuth applications for the following services by default on startu
 |-----------|-----------|---------|
 |[git-credential-oauth](https://github.com/hickford/git-credential-oauth)|Git credential helper|`a4792ccc-144e-407e-86c9-5e7d8d9c3269`|
 |[Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager)|Git credential helper|`e90ee53c-94e2-48ac-9358-a874fb9e0662`|
-|[Gitea CLI](https://gitea.com/gitea/cli)|Gitea CLI|`d57cb8c4-630c-4168-8324-ec79935e18d4`|
+|[tea](https://gitea.com/gitea/tea)|tea|`d57cb8c4-630c-4168-8324-ec79935e18d4`|
 |Gitea App|Official Gitea mobile app|`b757811a-05c8-4c76-8d74-a5ee3d2073f2`|
 |[gitea-vscode](https://gitea.com/gitea/gitea-vscode)|VS Code extension|`75a9ec3e-42b5-40cb-9144-9ea96ecd56a6`|
 To prevent unexpected behavior, they are being displayed as locked in the UI and their creation can instead be controlled by the `DEFAULT_APPLICATIONS` parameter in `app.ini`.
@@ -8,7 +8,7 @@ aliases:
 # Database Preparation
-You need a database to use Gitea. Gitea supports PostgreSQL (>= 12), MySQL (>= 8.0), MariaDB (>= 10.4), SQLite (builtin), and MSSQL (>= 2012 SP4). This page will guide into preparing database. PostgreSQL, MySQL and MSSQL are covered here. If you plan to use SQLite, you can ignore this chapter.
+You need a database to use Gitea. Gitea supports PostgreSQL (>= 12), MySQL (>= 8.0), MariaDB (>= 10.4), SQLite (builtin), and MSSQL (>= 2012 SP4). This page will guide into preparing database. Only PostgreSQL and MySQL will be covered here since those database engines are widely-used in production. If you plan to use SQLite, you can ignore this chapter.
 :::warning
 Converting one database type to another is not a well-tested process and you may experience issues. It is better to choose the final database type at the type of the first installation. Be aware that SQLite does not scale; if you expect your instance to grow at a later time, you should choose another database type.
@@ -177,28 +177,6 @@ All steps below requires that the database engine of your choice is installed on
    You should be prompted to enter password for the database user, and connected to the database.
 ## MSSQL
 1. As an administrator, create the login, a database with case-sensitive collation, and its user. Replace the password `'gitea'` with a secure one:
    ```sql
    CREATE LOGIN gitea WITH PASSWORD = 'gitea';
    CREATE DATABASE giteadb COLLATE Latin1_General_CS_AS;
    GO
    USE giteadb;
    CREATE USER gitea FOR LOGIN gitea;
    ALTER ROLE db_owner ADD MEMBER gitea;
    GO
    ```
    Upgrades change the database schema, so the user needs `db_owner`, or `db_ddladmin`, `db_datareader` and `db_datawriter`. With the latter, also run `ALTER DATABASE giteadb SET READ_COMMITTED_SNAPSHOT ON;` as administrator.
 2. On your Gitea server, test the connection to the database:
    ```sh
    sqlcmd -S 203.0.113.3 -U gitea -d giteadb
    ```
 ## Database Connection over TLS
 If the communication between Gitea and your database instance is performed through a private network, or if Gitea and the database are running on the same server, this section can be omitted since the security between Gitea and the database instance is not critically exposed. If instead the database instance is on a public network, use TLS to encrypt the connection to the database, as it is possible for third-parties to intercept the traffic data.
@@ -23,7 +23,7 @@ version is @minNodeVersion@ and the latest LTS version is recommended.
 :::note
 Go version @minGoVersion@ or higher is required. However, it is recommended to
 obtain the same version as our continuous integration, see the advice given in
-[Hacking on Gitea](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md)
+[Hacking on Gitea](development/hacking-on-gitea.md)
 :::
 ## Download
@@ -73,7 +73,7 @@ To build from source, the following programs must be present on the system:
 - `go` @minGoVersion@ or higher, see [here](https://go.dev/dl/)
 - `node` @minNodeVersion@ or higher with `npm`, see [here](https://nodejs.org/en/download/)
- `make`, see [here](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md#make)
+- `make`, see [here](development/hacking-on-gitea.md#installing-make)
 Various [make tasks](https://github.com/go-gitea/gitea/blob/main/Makefile)
 are provided to keep the build process as simple as possible.
@@ -0,0 +1,49 @@
 ---
 date: "2016-12-01T16:00:00+02:00"
 slug: "install-on-cloud-provider"
 sidebar_position: 90
 aliases:
  - /en-us/install-on-cloud-provider
 ---
 # Installation on Cloud Provider
 ## Cloudron
 Gitea is available as a 1-click install on [Cloudron](https://cloudron.io).
 Cloudron makes it easy to run apps like Gitea on your server and keep them up-to-date and secure.
 [![Install](/cloudron.svg)](https://cloudron.io/button.html?app=io.gitea.cloudronapp)
 The Gitea package is maintained [here](https://git.cloudron.io/cloudron/gitea-app).
 There is a [demo instance](https://my.demo.cloudron.io) (username: cloudron password: cloudron) where
 you can experiment with running Gitea.
 ## Linode
 [Linode](https://www.linode.com/) has Gitea as an app in their marketplace.
 To deploy Gitea to Linode, have a look at the [Linode Marketplace](https://www.linode.com/marketplace/apps/linode/gitea/).
 ## alwaysdata
 [alwaysdata](https://www.alwaysdata.com/) has Gitea as an app in their marketplace.
 To deploy Gitea to alwaysdata, have a look at the [alwaysdata Marketplace](https://www.alwaysdata.com/en/marketplace/gitea/).
 ## Exoscale
 [Exoscale](https://www.exoscale.com/) provides Gitea managed by [Glasskube](https://glasskube.eu/) in their marketplace.
 Exoscale is a European cloud service provider.
 The package is maintained and update via the open source [Glasskube Kubernetes Operator](https://github.com/glasskube/operator).
 To deploy Gitea to Exoscale, have a look at the [Exoscale Marketplace](https://www.exoscale.com/marketplace/listing/glasskube-gitea/).
 ## Sealos
 Gitea is available as a one-click deployment on [Sealos](https://sealos.io/products/app-store/gitea).
 The community-maintained template source is available [here](https://github.com/labring-actions/templates/tree/kb-0.9/template/gitea).
@@ -66,7 +66,7 @@ server-1  | 2026-03-11T12:57:50.796198843Z /var/lib/gitea/git is not writable
 server-1  | 2026-03-11T12:57:50.796235667Z docker setup failed
 ```
-For a stable release you could use `:latest-rootless`, `:1-rootless` or specify a certain release like `:@dockerVersion@-rootless`, but if you'd like to use the latest development version then `:main-nightly-rootless` would be an appropriate tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly-rootless` tag, where x is the minor version of Gitea. (e.g. `:1.27-nightly-rootless`)
+For a stable release you could use `:latest-rootless`, `:1-rootless` or specify a certain release like `:@dockerVersion@-rootless`, but if you'd like to use the latest development version then `:nightly-rootless` would be an appropriate tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly-rootless` tag, where x is the minor version of Gitea. (e.g. `:1.16-nightly-rootless`)
 ## Named volumes
@@ -30,7 +30,7 @@ image as a service. Since there is no database available, one can be initialized
 Create a directory like `gitea` and paste the following content into a file named `docker-compose.yml`.
 Note that the volume should be owned by the user/group with the UID/GID specified in the config file.
 If you don't give the volume correct permissions, the container may not start.
-For a stable release you can use `:latest`, `:1` or specify a certain release like `:@dockerVersion@`, but if you'd like to use the latest development version of Gitea then you could use the `:main-nightly` tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly` tag, where x is the minor version of Gitea. (e.g. `:1.27-nightly`)
+For a stable release you can use `:latest`, `:1` or specify a certain release like `:@dockerVersion@`, but if you'd like to use the latest development version of Gitea then you could use the `:nightly` tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly` tag, where x is the minor version of Gitea. (e.g. `:1.16-nightly`)
 ```yaml
 networks:
@@ -191,7 +191,7 @@ services:
 +    networks:
 +      - gitea
 +    volumes:
-+      - ./postgres:/var/lib/postgresql
+      - ./postgres:/var/lib/postgresql/data
 ```
 ## Named volumes
@@ -10,13 +10,13 @@ aliases:
 # Protected branches
-Protected branches prevent unwanted changes by enforcing push, deletion, and merge policies on selected branches. The rules are enforced for every Git protocol (HTTP(S), SSH), the web editor, the API, and background jobs such as auto-merge. Only repository owners and administrators can manage the rules, and the Branches page is read-only while a repository is archived.
+Protected branches prevent unwanted changes by enforcing push and merge policies on selected branches. The rules are enforced for every Git protocol (HTTP(S), SSH), the web editor, the API, and background jobs such as auto-merge. Only repository owners and administrators can manage the rules, and the Branches page is read-only while a repository is archived.
 ## Creating or editing a rule
 1. Open the repository and select **Settings → Branches** (repository admin permission required).
 2. Select **Add new rule** or **Edit** next to an existing rule.
-3. Fill in the **Protected branch name pattern** and optional file patterns, then configure the push, deletion, merge, and review options described below.
+3. Fill in the **Protected branch name pattern** and optional file patterns, then configure the push, merge, and review options described below.
 4. Select **Save rule**.
 The rule immediately applies to all matching branches, even if the branches are created in the future.
@@ -48,9 +48,7 @@ The **Push** section controls direct pushes (including the web editor and API).
 - **Disable push** makes the branch read-only. Any attempt to push directly fails, and changes must be merged through pull requests.
 - **Enable push** allows anyone with [write access](./permissions.md) to push (force pushes are still blocked unless explicitly allowed).
- **Allowlist restricted push** requires being on the allowlist. Choose users and, for organization-owned repositories, teams.
+- **Allowlist restricted push** requires being on the allowlist. Choose users and, for organization-owned repositories, teams. Deploy keys that already have write access can also be allowlisted.
 The user allowlists for push, force-push and deletion can include the **Gitea Actions** and **Deploy Key** system users. They still require write access; **Deploy Key** also covers deploy tokens.
 When a push is blocked, the server-side hook rejects the update with an explanation.
@@ -60,17 +58,7 @@ Force pushes have their own set of options:
 - **Disable force push** completely forbids rewriting history on the branch.
 - **Enable force push** allows anyone who can push to also force push.
- **Allowlist restricted force push** limits force pushes to a separate allowlist of users or teams **and** requires regular push access.
+- **Allowlist restricted force push** limits force pushes to a separate allowlist (users, teams, and optionally deploy keys) **and** requires the person to already have regular push access.
 ## Branch deletion
 The **Branch Deletion** section controls whether matching protected branches can be deleted:
 - **Disable branch deletion** prevents deletion. This is the default.
 - **Enable branch deletion** allows anyone who can push to delete the branch.
 - **Allowlist restricted branch deletion** limits deletion to a separate allowlist of users or teams **and** requires regular push access.
 These rules apply to Git (`git push --delete`), the API, the web interface and post-merge cleanup. The default branch and configured default pull request target branch cannot be deleted.
 ## Pull request merges and approvals
@@ -1,31 +0,0 @@
 ---
 date: "2026-08-30T00:00:00+02:00"
 slug: "artifacts"
 sidebar_position: 70
 ---
 # Artifacts
 Workflow runs can store files such as test results, coverage reports, and build output as artifacts. Artifacts are uploaded by workflows, for example with [`actions/upload-artifact`](https://github.com/actions/upload-artifact), and appear on the run page after the upload completes.
 ## Previewing artifacts
 Select an artifact on the run page to open its file browser and preview in the same tab. The preview identifies the originating run and attempt, and provides links back to that run and to download the complete artifact. Selecting files in the browser updates the preview in the same tab.
 Artifact previews:
 - require sign-in and access to the Actions run to open the preview page
 - render text-based files, images (including SVG), and PDFs
 - run HTML and JavaScript content in a sandboxed frame
 Preview content is loaded through signed URLs that expire after one hour and do not require a session cookie. Reopen the preview page to obtain a fresh URL after it expires.
 The file browser lists up to 2,000 files per artifact. Larger artifacts show a notice when the list is truncated.
 Unsupported or oversized files can still be downloaded with the complete artifact.
 ## Instance configuration
 Site administrators can limit the total artifact size that can be browsed or previewed with `ARTIFACT_PREVIEW_MAX_SIZE` in the `[actions]` section of `app.ini`. The default is 10 MiB. Set it to `0` to disable previews or `-1` to allow artifacts of any size.
 The size of an individual previewed file is also limited by [`MAX_DISPLAY_FILE_SIZE`](../../administration/config-cheat-sheet.md#ui-ui) in the `[ui]` section.
@@ -6,87 +6,104 @@ sidebar_position: 120
 # Compared to GitHub Actions
-Gitea Actions is designed to be compatible with GitHub Actions, with the differences below.
+Even though Gitea Actions is designed to be compatible with GitHub Actions, there are some differences between them.
 ## Additional features
 ### Absolute action URLs
-`uses:` accepts an absolute URL to any git host, e.g. `uses: https://gitea.com/actions/checkout@v4`.
+Gitea Actions supports defining actions via absolute URL, which means that you can use actions from any git repository.
-
+Like `uses: https://github.com/actions/checkout@v4` or `uses: http://your_gitea.com/owner/repo@branch`.
 ### Action prefixes
 `uses:` accepts these prefixes:
 - `self:` references your own Gitea instance, e.g. `uses: self:owner/repo@v1` or `uses: self:owner/repo/.gitea/workflows/build.yml@v1`
 - `builtin:` runs an action built into Gitea Runner, which needs no download and does not depend on Node.js, e.g. `uses: builtin:checkout`
 ### Actions written in Go
 Gitea Actions supports writing actions in Go.
 See [Creating Go Actions](https://blog.gitea.com/creating-go-actions/).
 ### Support the non-standard syntax @yearly, @monthly, @weekly, @daily, @hourly on schedule
-`schedule` also accepts `@yearly`, `@monthly`, `@weekly`, `@daily` and `@hourly`, which [GitHub does not](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule).
+Github Actions doesn't support that. https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule
 ## Unsupported workflows syntax
 ### `jobs.<job_id>.environment`
-[`jobs.<job_id>.environment`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment) is ignored.
+See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment).
 It's ignored by Gitea Actions now.
 ### Complex `runs-on`
-[`runs-on`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on) supports:
+See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on).
 Gitea Actions supports:
 - Static strings: `runs-on: self-hosted`
 - Arrays of labels: `runs-on: [linux, self-hosted]`
 - String expressions: `runs-on: ${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}`
 - Arrays containing expressions: `runs-on: [linux, "${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}"]`
 ## Missing features
 ### Package repository authorization
-`GITEA_TOKEN` cannot publish to the package registry of its repository, e.g. to push OCI images.
+The `GITEA_TOKEN` for a job running within a repository should be able to publish to the associated package repository (i.e. to upload OCI images). See the "packages" scope for the "default access" in [Automatic token authentication](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token).
-Use a personal access token instead, see [this issue](https://github.com/go-gitea/gitea/issues/23642#issuecomment-2119876692).
+
 This is not implemented in Gitea Actions now. A workaround for Gitea Actions is to use a Personal Access Token (PAT). See this [github issue and comment](https://github.com/go-gitea/gitea/issues/23642#issuecomment-2119876692) for tracking this feature.
 ### Problem Matchers
-[Problem matchers](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md) are ignored.
+Problem Matchers are a way to scan the output of actions for a specified regex pattern and surface that information prominently in the UI.
 See [Problem matchers](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md).
 It's ignored by Gitea Actions now.
 ### Create an error annotation
-[Error annotations](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error) are ignored.
+See [Creating an annotation for an error](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error)
 It's ignored by Gitea Actions now.
 ### Expressions
-[Expressions](https://docs.github.com/en/actions/learn-github-actions/expressions) support the standard GitHub functions and contexts.
+For [expressions](https://docs.github.com/en/actions/learn-github-actions/expressions), Gitea Actions supports standard GitHub functions (e.g. `success()`, `failure()`, `always()`, `cancelled()`, `format()`, `toJSON()`) and context variables (like `github`, `matrix`, `vars`, `env`).
 ## Missing UI features
 ### Pre and Post steps
-Pre and post steps have no section of their own in the job log.
+Pre and Post steps don't have their own section in the job log user interface.
 ### Services steps
-Service steps have no section of their own in the job log.
+Services steps don't have their own section in the job log user interface.
 ## Different behavior
 ### Job token permissions (`permissions`)
-`permissions` and `jobs.<job_id>.permissions` control the `GITEA_TOKEN` permissions, clamped by the repository and owner settings and further restricted for fork pull requests and cross-repository access.
+Gitea supports `permissions` and `jobs.<job_id>.permissions` to control the default `GITEA_TOKEN` permissions.
-GitHub-only scopes like `statuses`, `checks`, `deployments`, `security-events` and `pages` are not supported, while Gitea adds `code`, `releases`, `wiki` and `projects`. `id-token` works like on GitHub, see [OpenID Connect](openid-connect.md).
+
 The effective permissions are clamped by the repository/owner settings and are further restricted for fork pull requests and cross-repository access.
 GitHub-only scopes such as `statuses`, `checks`, `deployments`, `id-token`, `security-events`, and `pages` are not supported, while Gitea-specific scopes such as `code`, `releases`, `wiki`, and `projects` are available.
 See [Actions job token permissions](token-permissions.md).
 ### Downloading actions
-Actions without a host, like `uses: actions/checkout@v4`, are downloaded from `https://github.com`, or from your own instance when `[actions].DEFAULT_ACTIONS_URL` is `self`.
+Previously (Pre 1.21.0), `[actions].DEFAULT_ACTIONS_URL` defaulted to `https://gitea.com`.
-See the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions).
+We have since restricted this option to only allow two values (`github` and `self`).
-For other sources, see [Absolute action URLs](#absolute-action-urls) and [Action prefixes](#action-prefixes).
+When set to `github`, the new default, Gitea will download non-fully-qualified actions from `https://github.com`.
 For example, if you use `uses: actions/checkout@v4`, it will download the checkout repository from `https://github.com/actions/checkout.git`.
 If you want to download an action from another git hoster, you can use an absolute URL, e.g. `uses: https://gitea.com/actions/checkout@v4`.
 If your Gitea instance is in an intranet or a restricted area, you can set the URL to `self` to only download actions from your own instance by default.
 Of course, you can still use absolute URLs in workflows.
 More details about the `[actions].DEFAULT_ACTIONS_URL` configuration can be found in the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions)。
 ### Context availability
-[Context availability](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability) is not checked, so contexts like `env` work in more places.
+Context availability is not checked, so you can use the env context on more places.
 See [Context availability](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability).
@@ -19,7 +19,7 @@ Additionally, the runner will introduce itself to Gitea and declare what kind of
 Earlier, we mentioned that `runs-on: ubuntu-latest` in a workflow file means that the job will be run on a runner with the `ubuntu-latest` label.
 But how does the runner know to run `ubuntu-latest`? The answer lies in mapping the label to an environment.
-That's why each label of a runner names an environment, like `my_custom_label:docker://centos:7`.
+That's why when you add custom labels during registration, you will need to input some complex content like `my_custom_label:docker://centos:7`.
 This means that the runner can take the job which needs to run on `my_custom_label`, and it will run it via a docker container with the image `centos:7`.
 Docker isn't the only option, though.
@@ -34,6 +34,7 @@ So,
 - `my_custom_label:docker://node:18`: Run jobs labeled with `my_custom_label` using the `node:18` Docker image.
 - `my_custom_label:host`: Run jobs labeled with `my_custom_label` directly on the host.
 - `my_custom_label`: Same as `my_custom_label:host`.
 - `my_custom_label:vm:ubuntu-latest`: (Example only, not implemented) Run jobs labeled with `my_custom_label` using a virtual machine with the `ubuntu-latest` ISO.
 ## Communication protocol
@@ -42,7 +43,7 @@ However, we did not think it was a good idea to have Gitea listen on a new port.
 Instead, we wanted to reuse the HTTP port, which means we needed a protocol that is compatible with HTTP.
 We chose to use gRPC over HTTP.
-The protocol is defined in [actions-proto-def](https://gitea.com/gitea/actions-proto-def), its Go code lives in [actionslib](https://gitea.com/gitea/actionslib).
+We use [actions-proto-def](https://gitea.com/gitea/actions-proto-def) and [actions-proto-go](https://gitea.com/gitea/actions-proto-go) to wire them up.
 More information about gRPC can be found on [its website](https://grpc.io/).
 ## Network architecture
@@ -70,8 +71,7 @@ However, if a job container tries to fetch code from localhost, it will fail bec
 ### Connection 3, runner to internet
 When you use some actions like `actions/checkout@v4`, the runner downloads the scripts, not the job containers.
-By default, it downloads them from [github.com](https://github.com/), which requires internet access.
+By default, it downloads from [github.com](http://github.com/), so it requires access to the internet. If you configure the `DEFAULT_ACTIONS_URL` to `self`, then it will download from your Gitea instance by default. Then it will not connect to internet when downloading the action itself.
 With `DEFAULT_ACTIONS_URL` set to `self`, or with `uses: self:owner/repo@ref`, it downloads them from your Gitea instance instead.
 It also downloads some docker images from Docker Hub by default, which also requires internet access.
 However, internet access is not strictly necessary.
@@ -27,24 +27,50 @@ Still, this is completely optional since both options have the same effect at th
 ## Where will the runner download scripts when using actions such as `actions/checkout@v4`?
-From `https://github.com` by default, or from your own instance when `[actions].DEFAULT_ACTIONS_URL` is `self`, see the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions).
+There are tens of thousands of [actions scripts](https://github.com/marketplace?type=actions) in GitHub, and when you write `uses: actions/checkout@v4`, it downloads the scripts from [github.com/actions/checkout](http://github.com/actions/checkout) by default.
 But what if you want to use actions from other places such as gitea.com instead of GitHub?
-To use an action from elsewhere, name its host:
+The good news is that you can specify the URL prefix to use actions from anywhere.
 This is an extra syntax in Gitea Actions.
 For example:
- `uses: https://gitea.com/owner/repo@ref`
+- `uses: https://gitea.com/xxx/xxx@xxx`
- `uses: http://your_gitea_instance.com/owner/repo@ref`
+- `uses: https://github.com/xxx/xxx@xxx`
- `uses: self:owner/repo@ref` for your own Gitea instance
+- `uses: http://your_gitea_instance.com/xxx@xxx`
 Be careful, the `https://` or `http://` prefix is necessary!
 This is one of the differences from GitHub Actions which supports actions scripts only from GitHub.
 But it should allow users much more flexibility in how they run Actions.
 Alternatively, if you want your runners to download actions from your own Gitea instance by default, you can configure it by setting `[actions].DEFAULT_ACTIONS_URL`.
 See [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions).
 ## How to limit the permission of the runners?
-Runners only connect to your Gitea instance.
+Runners have no more permissions than simply connecting to your Gitea instance.
-For each job, a runner gets a `GITEA_TOKEN` limited to the job's repository, see [Actions job token permissions](token-permissions.md).
+When any runner receives a job to run, it will temporarily gain limited permission to the repository associated with the job.
-To give a job access to more private repositories or external systems, pass it [secrets](usage/actions/secrets.md).
+If you want to give more permissions to the runner, allowing it to access more private repositories or external systems, you can pass [secrets](usage/actions/secrets.md) to it.
 Refined permission control to Actions is a complicated job.
 In the future, we will add more options to Gitea to make it more configurable, such as allowing more write access to repositories or read access to all repositories in the same organization.
 ## Which operating systems are supported by Gitea Runner?
-Official binaries are released for Linux, macOS and Windows.
+We released official binaries for Linux, macOS, and Windows.
-Other systems supported by Go and Docker work in theory.
+While other operating systems are theoretically supported if it is supported by golang and docker(docker mode enabled).
 One thing to note is that if you choose to run jobs directly on the host instead of in job containers, the environmental differences between operating systems may cause unexpected failures.
 For example, bash is not available on Windows in most cases, while act tries to use bash to run scripts by default.
 Therefore, you need to specify `powershell` as the default shell in your workflow file, see [defaults.run](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun).
 ```yaml
 defaults:
  run:
    shell: powershell
 ```
 ## How to avoid being hacked?
@@ -73,13 +99,42 @@ It is exciting to be able to reuse them.
 ## What if it runs on multiple labels, such as `runs-on: [label_a, label_b]`?
-The job runs on a runner that has all of the labels, as on [GitHub](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on).
+This is valid syntax.
-The runner uses the environment of the first label it has.
+It means that it should run on runners that have both the `label_a` **and** `label_b` labels, see [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on).
 Unfortunately, the runner does not work this way until v0.2.11.
 As mentioned, we map labels to environments:
 - `ubuntu` → `ubuntu:22.04`
 - `centos` → `centos:8`
 But we need to map label groups to environments instead, like so:
 - `[ubuntu]` → `ubuntu:22.04`
 - `[with-gpu]` → `linux:with-gpu`
 - `[ubuntu, with-gpu]` → `ubuntu:22.04_with-gpu`
 We also need to re-design how tasks are assigned to runners.
 A runner with `ubuntu`, `centos`, or `with-gpu` does not necessarily indicate that it can accept jobs with `[centos, with-gpu]`.
 Therefore, the runner should inform the Gitea instance that it can only accept jobs with `[ubuntu]`, `[centos]`, `[with-gpu]`, and `[ubuntu, with-gpu]`.
 This is not a technical problem, it was just overlooked in the early design.
 See [runtime.go#L65](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65).
 Currently, the runner attempts to match everyone in the labels and uses the first match it finds.
 ## What is the difference between agent labels and custom labels for a runner?
-Gitea no longer has custom labels.
+![labels](/images/usage/actions/labels.png)
-A runner declares its labels every time it starts, from its `runner.labels` configuration or the labels given at registration, so change them there and restart the runner.
+
 Agent labels are reported to the Gitea instance by the runner during registration.
 Custom labels, on the other hand, are added manually by a Gitea administrator or owners of the organization or repository (depending on the level of the runner).
 However, the design here needs improvement, as it currently has some rough edges.
 You can add a custom label such as `centos` to a registered runner, which means the runner will receive jobs with `runs-on: centos`.
 However, the runner may not know which environment to use for this label, resulting in it using a default image or leading to a logical dead end.
 This default may not match user expectations.
 See [runtime.go#L71](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71).
 In the meantime, we suggest that you re-register your runner if you want to change its labels.
 ## Will there be more implementations for Gitea Actions runner?
@@ -122,6 +177,3 @@ For events supported only by GitHub, see GitHub's [documentation](https://docs.g
 Go to the repository's **Settings** > **Actions** > **General** page and add collaborative owners.
 The private repositories of collaborative owners are allowed to access the actions and workflows in the current repository.
 To share within the same user or organization, add the private repositories under its **Settings** > **Actions** > **General** > **Cross-Repository Access** instead.
 See [Cross-repository access](token-permissions.md#cross-repository-access).
@@ -1,60 +0,0 @@
 ---
 date: "2026-08-23T00:00:00+00:00"
 slug: "openid-connect"
 sidebar_position: 40
 ---
 # OpenID Connect
 Jobs can request short-lived OpenID Connect (OIDC) tokens to sign in to cloud providers and other services without storing long-lived secrets. The tokens use the GitHub Actions format, so actions like `aws-actions/configure-aws-credentials`, `google-github-actions/auth` and `azure/login` work unchanged.
 ## Trusting Gitea
 Add Gitea as an OIDC identity provider in the service:
 - Issuer: `<ROOT_URL>/api/actions/oidc`
 - Audience: `<ROOT_URL>/<owner>`, unless the workflow requests another one
 Then limit which workflows can sign in with a condition on the [`sub` claim](#claims).
 Gitea signs the tokens with a key it creates at `<APP_DATA_PATH>/jwt/actions_oidc.pem`. Instances behind a load balancer must share this file.
 ## Requesting a token
 Grant the `id-token` permission to the workflow or job:
 ```yaml
 permissions:
  id-token: write
 ```
 Default permissions never include it, and jobs from fork pull requests never get it. Owners and repositories can disable it with their [maximum token permissions](token-permissions.md#maximum-token-permissions-clamping).
 Actions like the ones above request the token themselves. In a script, use `ACTIONS_ID_TOKEN_REQUEST_URL` and `ACTIONS_ID_TOKEN_REQUEST_TOKEN`:
 ```shell
 curl --fail --silent --show-error \
  --header "Authorization: Bearer ${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" \
  "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=my-service"
 ```
 The token is in the `value` field of the response and expires after five minutes.
 ## Claims
 The `sub` claim names the owner and repository with their IDs, so a renamed or recreated repository cannot match an existing trust policy:
 ```text
 repo:<owner>@<owner-id>/<repo>@<repo-id>:ref:<ref>
 repo:<owner>@<owner-id>/<repo>@<repo-id>:pull_request
 ```
 The `pull_request` event uses the second form, all other events use the first, including `pull_request_target`.
 The other claims match GitHub's, like `repository`, `ref`, `sha`, `workflow_ref` and `job_workflow_ref`. The discovery document at `<ROOT_URL>/api/actions/oidc/.well-known/openid-configuration` lists them all.
 Differences from GitHub Actions:
 - There is no `environment` claim.
 - Pull request runs use `refs/pull/<index>/head` and its commit, not the merge ref and merge commit.
 - `run_number` counts runs per repository, not per workflow.
@@ -40,7 +40,7 @@ However, it is recommended to use Docker to run the jobs, because it is more sec
 Before running a runner, you should first register it to your Gitea instance using the following command:
 ```bash
-gitea-runner register --no-interactive --instance <instance> --token <token>
+./runner register --no-interactive --instance <instance> --token <token>
 ```
 There are two arguments required, `instance` and `token`.
@@ -69,7 +69,7 @@ If this file is missing or corrupted, you can simply remove it and register agai
 Finally, it's time to start the runner:
 ```bash
-gitea-runner daemon
+./runner daemon
 ```
 And you can see the new runner in the management page:
@@ -102,8 +102,8 @@ Only a workflow that runs on an event that posts a commit status (`push`, `pull_
 Scoped workflows can call reusable workflows:
- A **local** reference (`uses: ./...` or `uses: $/...`) resolves against the **source** repository: the repository the calling workflow's content came from, not the consuming repository.
+- A **local** reference (`uses: ./...`) resolves against the **source** repository: the repository the calling workflow's content came from, not the consuming repository.
- A **cross-repository** reference (`uses: owner/repo/...@ref` or `uses: self:owner/repo/...@ref`) is resolved with the **consuming repository's** read permission. If it points to a private repository, make sure every consuming repository can read it; otherwise the workflow will fail there.
+- A **cross-repository** reference (`uses: owner/repo/...@ref`) is resolved with the **consuming repository's** read permission. If it points to a private repository, make sure every consuming repository can read it; otherwise the workflow will fail there.
 A reusable workflow can live under `SCOPED_WORKFLOW_DIRS` (or `WORKFLOW_DIRS`) of the source repository.
@@ -53,14 +53,13 @@ Valid access mode values for each scope are `read`, `write`, and `none`.
 - `wiki`
 - `projects`
 - `packages` (if supported by the target feature)
 - `id-token` (`write` allows requesting [OpenID Connect tokens](openid-connect.md), `read` grants nothing)
 If you specify both `contents` and a more granular scope (like `code` or `releases`), the granular scope wins for that unit.
 ### Compatibility notes
 Gitea supports a subset of GitHub Actions permission scopes.
-GitHub-only scopes such as `statuses`, `checks`, `deployments`, `security-events`, and `pages` are not currently supported by Gitea Actions.
+GitHub-only scopes such as `statuses`, `checks`, `deployments`, `id-token`, `security-events`, and `pages` are not currently supported by Gitea Actions.
 Gitea also exposes repository-unit scopes that do not exist as separate scopes in GitHub Actions:
@@ -76,18 +75,15 @@ If neither the workflow nor the job defines `permissions:`, Gitea uses the confi
 - **Permissive**: read and write permissions for most units in the job's repository (backwards-compatible default).
 - **Restricted**: read-only permissions for `code`, `releases`, and `packages` in the job's repository, and no access to other units by default.
 Neither mode includes `id-token`.
 ## Maximum token permissions (clamping)
-You can configure a maximum permission per repository unit and for `id-token`.
+You can configure a maximum permission per repository unit.
 The job's effective permissions are computed as:
 `effective = min(requested, maximum)`
 This means workflows can reduce permissions for a job, but cannot exceed your configured maximum.
 If you don't configure a maximum, the maximum defaults to `write` for all scopes.
 Maximums saved before Gitea supported `id-token` deny it until you set it to `write`.
 ## Where to configure
@@ -99,13 +95,9 @@ You can configure defaults and maximums at:
 Note: Repository-level token permission settings are only shown once **Repository Actions** are enabled.
 ## Protected branches
 Actions job tokens must have code write permission and satisfy [branch protection rules](../access-control/protected-branches.md), including any **Gitea Actions** allowlist requirements.
 ## Fork pull requests
-For security reasons, workflows triggered by pull requests from forks are always restricted to read-only permissions for repository contents, regardless of workflow `permissions:` or settings. They also get no OpenID Connect tokens.
+For security reasons, workflows triggered by pull requests from forks are always restricted to read-only permissions for repository contents, regardless of workflow `permissions:` or settings.
 ## Cross-repository access
@@ -9,67 +9,53 @@ sidebar_position: 25
 ## Environment variables
 These environment variables are set automatically in every workflow run and can be accessed directly (e.g. `$CI` in shell scripts).
 A `GITEA_*` name listed with a `GITHUB_*` name holds the same value.
 | Name | Description | Example |
 |---|---|---|
 | `ACT` | Always set to `true`, unless the runner is configured with `runner.set_act_env: false`. | `true` |
 | `CI` | Always set to `true`. | `true` |
-| `GITEA_ACTION`<br/>`GITHUB_ACTION` | The `id` of the current step, or its index when it has none. | `0` |
+| `GITEA_ACTIONS` | Always set to `true`. Useful to distinguish Gitea Actions from other CI systems. | `true` |
-| `GITEA_ACTION_PATH`<br/>`GITHUB_ACTION_PATH` | The path where the action is located. Only set in composite actions. | `/var/run/act/actions/***` |
+| `GITEA_ACTIONS_RUNNER_VERSION` | The version of the runner executing the workflow. | `1.0.8` |
-| `GITEA_ACTION_REF`<br/>`GITHUB_ACTION_REF` | The ref of the action being executed. | `v4` |
+| `GITEA_DOCKER_WORKSPACE` | The workspace path as the Docker daemon sees it, for bind mounts into containers a job starts, e.g. `${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data` in a compose file. Only set for jobs running in a container. | `/var/lib/docker/volumes/GITEA-ACTIONS-TASK-42_***/_data` |
-| `GITEA_ACTION_REPOSITORY`<br/>`GITHUB_ACTION_REPOSITORY` | The owner and repository of the action. | `actions/checkout` |
+| `GITEA_ENV`<br/>`GITHUB_ENV` | Path to the file that sets environment variables for subsequent steps. | `/home/runner/work/_temp/_runner_file_commands/set_env_***` |
-| `GITEA_ACTIONS`<br/>`GITHUB_ACTIONS` | Always set to `true`. `GITEA_ACTIONS` is useful to distinguish Gitea Actions from other CI systems. | `true` |
+| `GITEA_OUTPUT`<br/>`GITHUB_OUTPUT` | Path to the file that sets step output parameters. | `/home/runner/work/_temp/_runner_file_commands/set_output_***` |
-| `GITEA_ACTIONS_RUNNER_VERSION` | The version of the runner executing the workflow. | `v5.2.4` |
+| `GITEA_PATH`<br/>`GITHUB_PATH` | Path to the file that adds system `PATH` entries for subsequent steps. | `/home/runner/work/_temp/_runner_file_commands/add_path_***` |
-| `GITEA_ACTOR`<br/>`GITHUB_ACTOR` | The username of the user that triggered the workflow. | `alice` |
+| `GITEA_STATE`<br/>`GITHUB_STATE` | Path to the file that sets step state variables. | `/home/runner/work/_temp/_runner_file_commands/save_state_***` |
-| `GITEA_ACTOR_ID`<br/>`GITHUB_ACTOR_ID` | The ID of the user that triggered the workflow. | `1` |
+| `GITEA_STEP_SUMMARY`<br/>`GITHUB_STEP_SUMMARY` | Path to the file for writing job summaries. | `/home/runner/work/_temp/_runner_file_commands/step_summary_***` |
-| `GITEA_API_URL`<br/>`GITHUB_API_URL` | The URL of the REST API. | `https://gitea.example.com/api/v1` |
+| `GITHUB_ACTIONS` | Always set to `true`. | `true` |
-| `GITEA_BASE_REF`<br/>`GITHUB_BASE_REF` | The target branch of a pull request. | `main` |
+| `GITHUB_ACTION` | The name of the action currently running, or the step `id`. | `__run` |
-| `GITEA_DOCKER_WORKSPACE` | The workspace path as the Docker daemon sees it, for bind mounts into containers a job starts, e.g. `${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data` in a compose file. Only set for jobs running in a container. | `/var/lib/docker/volumes/GITEA-ACTIONS-TASK-42-***/_data` |
+| `GITHUB_ACTION_PATH` | The path where the action is located. | `/home/runner/work/_actions/actions/checkout/v4` |
-| `GITEA_ENV`<br/>`GITHUB_ENV` | Path to the file that sets environment variables for subsequent steps. | `/var/run/act/workflow/envs.txt` |
+| `GITHUB_ACTION_REF` | The ref of the action being executed. | `v4` |
-| `GITEA_EVENT_NAME`<br/>`GITHUB_EVENT_NAME` | The name of the event that triggered the workflow. | `push` |
+| `GITHUB_ACTION_REPOSITORY` | The owner and repository of the action. | `actions/checkout` |
-| `GITEA_EVENT_PATH`<br/>`GITHUB_EVENT_PATH` | Path to the file containing the event webhook payload. | `/var/run/act/workflow/event.json` |
+| `GITHUB_ACTOR` | The username of the user that triggered the workflow. | `silverwind` |
-| `GITEA_GRAPHQL_URL`<br/>`GITHUB_GRAPHQL_URL` | Empty in Gitea (GraphQL is not supported). | _(empty)_ |
+| `GITHUB_API_URL` | The URL of the REST API. | `https://gitea.com/api/v1` |
-| `GITEA_HEAD_REF`<br/>`GITHUB_HEAD_REF` | The source branch of a pull request. | `feature-branch` |
+| `GITHUB_BASE_REF` | The target branch of a pull request. | `main` |
-| `GITEA_JOB`<br/>`GITHUB_JOB` | The `job_id` of the current job. | `build` |
+| `GITHUB_EVENT_NAME` | The name of the event that triggered the workflow. | `push` |
-| `GITEA_OUTPUT`<br/>`GITHUB_OUTPUT` | Path to the file that sets step output parameters. | `/var/run/act/workflow/outputcmd.txt` |
+| `GITHUB_EVENT_PATH` | Path to the file containing the event webhook payload. | `/home/runner/work/_temp/_github_workflow/event.json` |
-| `GITEA_PATH`<br/>`GITHUB_PATH` | Path to the file that adds system `PATH` entries for subsequent steps. | `/var/run/act/workflow/pathcmd.txt` |
+| `GITHUB_GRAPHQL_URL` | Empty in Gitea (GraphQL is not supported). | _(empty)_ |
-| `GITEA_REF`<br/>`GITHUB_REF` | The fully-formed ref that triggered the workflow. | `refs/heads/main` |
+| `GITHUB_HEAD_REF` | The source branch of a pull request. | `feature-branch` |
-| `GITEA_REF_NAME`<br/>`GITHUB_REF_NAME` | The short ref name. | `main` |
+| `GITHUB_JOB` | The `job_id` of the current job. | `build` |
-| `GITEA_REF_PROTECTED`<br/>`GITHUB_REF_PROTECTED` | `true` if branch protections are configured for the ref that triggered the workflow. | `true` |
+| `GITHUB_REF` | The fully-formed ref that triggered the workflow. | `refs/heads/main` |
-| `GITEA_REF_TYPE`<br/>`GITHUB_REF_TYPE` | The type of ref: `branch` or `tag`. | `branch` |
+| `GITHUB_REF_NAME` | The short ref name. | `main` |
-| `GITEA_REPOSITORY`<br/>`GITHUB_REPOSITORY` | The owner and repository name. | `owner/repo` |
+| `GITHUB_REF_TYPE` | The type of ref: `branch` or `tag`. | `branch` |
-| `GITEA_REPOSITORY_ID`<br/>`GITHUB_REPOSITORY_ID` | The ID of the repository. | `123` |
+| `GITHUB_REPOSITORY` | The owner and repository name. | `gitea/docs` |
-| `GITEA_REPOSITORY_OWNER`<br/>`GITHUB_REPOSITORY_OWNER` | The repository owner's username. | `owner` |
+| `GITHUB_REPOSITORY_OWNER` | The repository owner's username. | `gitea` |
-| `GITEA_REPOSITORY_OWNER_ID`<br/>`GITHUB_REPOSITORY_OWNER_ID` | The ID of the repository owner. | `45` |
+| `GITHUB_RETENTION_DAYS` | The number of days that workflow run logs and artifacts are kept. | `90` |
-| `GITEA_RETENTION_DAYS`<br/>`GITHUB_RETENTION_DAYS` | The number of days that artifacts are kept, empty when kept forever. | `90` |
+| `GITHUB_RUN_ATTEMPT` | The attempt number of the workflow run. | `1` |
-| `GITEA_RUN_ATTEMPT`<br/>`GITHUB_RUN_ATTEMPT` | The attempt number of the workflow run. | `1` |
+| `GITHUB_RUN_ID` | A unique number for each workflow run. | `1234` |
-| `GITEA_RUN_ID`<br/>`GITHUB_RUN_ID` | A unique number for each workflow run. | `1234` |
+| `GITHUB_RUN_NUMBER` | A unique number for each run of a particular workflow. | `42` |
-| `GITEA_RUN_NUMBER`<br/>`GITHUB_RUN_NUMBER` | A unique number for each run of a particular workflow. | `42` |
+| `GITHUB_SERVER_URL` | The URL of the Gitea instance. | `https://gitea.com` |
-| `GITEA_SERVER_URL`<br/>`GITHUB_SERVER_URL` | The URL of the Gitea instance. | `https://gitea.example.com` |
+| `GITHUB_SHA` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
-| `GITEA_SHA`<br/>`GITHUB_SHA` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
+| `GITHUB_WORKFLOW` | The name of the workflow. | `CI` |
-| `GITEA_STATE`<br/>`GITHUB_STATE` | Path to the file that sets step state variables. | `/var/run/act/workflow/statecmd.txt` |
+| `GITHUB_WORKSPACE` | The default working directory on the runner. | `/workspace/gitea/docs` |
 | `GITEA_STEP_SUMMARY`<br/>`GITHUB_STEP_SUMMARY` | Path to the file for writing job summaries. | `/var/run/act/workflow/step-summary-0.md` |
 | `GITEA_TRIGGERING_ACTOR`<br/>`GITHUB_TRIGGERING_ACTOR` | The username of the user that initiated the workflow run. May differ from `GITEA_ACTOR` on re-runs. | `alice` |
 | `GITEA_WORKFLOW`<br/>`GITHUB_WORKFLOW` | The name of the workflow. | `CI` |
 | `GITEA_WORKFLOW_SHA`<br/>`GITHUB_WORKFLOW_SHA` | The commit SHA of the workflow file. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
 | `GITEA_WORKSPACE`<br/>`GITHUB_WORKSPACE` | The default working directory on the runner. | `/workspace/owner/repo` |
 | `TRACEPARENT` | The W3C trace context of the job's span, so instrumented tools can add spans to the job's trace. Only set when the runner exports traces, see [Monitoring](/runner/monitoring/#opentelemetry). | `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01` |
 | `TRACESTATE` | Vendor-specific trace data that accompanies `TRACEPARENT`. Only set when the trace carries any. | `rojo=00f067aa0ba902b7` |
 ### Runner environment variables
 | Name | Description | Example |
 |---|---|---|
 | `ImageOS` | The OS and release of the job's image, read by `setup-*` actions. | `ubuntu24` |
 | `RUNNER_ARCH` | The architecture of the runner. | `X64` |
 | `RUNNER_DEBUG` | Set to `1` when the `ACTIONS_STEP_DEBUG` secret is `true`, unset otherwise. | `1` |
 | `RUNNER_ENVIRONMENT` | Always set to `self-hosted`. | `self-hosted` |
 | `RUNNER_NAME` | The name of the runner executing the job. | `my-runner` |
 | `RUNNER_OS` | The operating system of the runner. | `Linux` |
 | `RUNNER_TEMP` | Path to a temporary directory on the runner. | `/tmp` |
 | `RUNNER_TOOL_CACHE` | Path to the tool cache directory on the runner. | `/opt/hostedtoolcache` |
 | `RUNNER_WORKSPACE` | The parent directory of `GITEA_WORKSPACE`. | `/workspace/owner` |
 ### Internal environment variables
@@ -78,11 +64,11 @@ These are used internally by the runner and actions. They are typically not need
 | Name | Description | Example |
 |---|---|---|
 | `ACTIONS_CACHE_URL` | URL for the actions cache service. | `http://192.168.1.10:8088/` |
-| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | Token for OIDC requests. Only set when `id-token: write` is granted. | `***` |
+| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | Token for OIDC requests. Only set when configured. | `***` |
-| `ACTIONS_ID_TOKEN_REQUEST_URL` | URL to request OIDC tokens. Only set when `id-token: write` is granted. | `https://gitea.example.com/api/actions/oidc/token?` |
+| `ACTIONS_ID_TOKEN_REQUEST_URL` | URL to request OIDC tokens. Only set when configured. | `https://gitea.com/login/oauth/access_token` |
-| `ACTIONS_RESULTS_URL` | URL for storing artifacts. | `https://gitea.example.com` |
+| `ACTIONS_RESULTS_URL` | URL for storing artifacts. | `https://gitea.com` |
 | `ACTIONS_RUNTIME_TOKEN` | Authentication token for the Actions pipeline API. | `***` |
-| `ACTIONS_RUNTIME_URL` | URL for the Gitea Actions pipeline API. | `https://gitea.example.com/api/actions_pipeline/` |
+| `ACTIONS_RUNTIME_URL` | URL for the Gitea Actions pipeline API. | `https://gitea.com/api/actions_pipeline/` |
 ## Context variables
@@ -90,39 +76,39 @@ These variables are available in workflow expressions via `${{ gitea.<name> }}`.
 | Name | Description | Example |
 |---|---|---|
-| `gitea.action`<br/>`github.action` | The `id` of the current step, or its index when it has none. | `0` |
+| `gitea.action`<br/>`github.action` | The name of the action currently running, or the `id` of a step. | `__run` |
-| `gitea.action_path`<br/>`github.action_path` | The path where an action is located. Only supported in composite actions. | `/var/run/act/actions/***` |
+| `gitea.action_path`<br/>`github.action_path` | The path where an action is located. Only supported in composite actions. | `/home/runner/work/_actions/actions/checkout/v4` |
 | `gitea.action_ref`<br/>`github.action_ref` | The ref of the action being executed. | `v4` |
 | `gitea.action_repository`<br/>`github.action_repository` | The owner and repository name of the action. | `actions/checkout` |
 | `gitea.action_status`<br/>`github.action_status` | The current result of a composite action. | `success` |
-| `gitea.actor`<br/>`github.actor` | The username of the user that triggered the initial workflow run. | `alice` |
+| `gitea.actor`<br/>`github.actor` | The username of the user that triggered the initial workflow run. | `silverwind` |
-| `gitea.api_url`<br/>`github.api_url` | The URL of the REST API. | `https://gitea.example.com/api/v1` |
+| `gitea.api_url`<br/>`github.api_url` | The URL of the REST API. | `https://gitea.com/api/v1` |
 | `gitea.base_ref`<br/>`github.base_ref` | The target branch of a pull request. Only set for `pull_request` and `pull_request_target` events. | `main` |
-| `gitea.env`<br/>`github.env` | Path on the runner to the file that sets environment variables from workflow commands. | `/var/run/act/workflow/envs.txt` |
+| `gitea.env`<br/>`github.env` | Path on the runner to the file that sets environment variables from workflow commands. Unique to each step. | `/home/runner/work/_temp/_runner_file_commands/set_env_***` |
 | `gitea.event`<br/>`github.event` | The full event webhook payload as an object. See [Event payload](#event-payload). | `{...}` |
 | `gitea.event_name`<br/>`github.event_name` | The name of the event that triggered the workflow run. | `push` |
-| `gitea.event_path`<br/>`github.event_path` | Path on the runner to the file containing the full event webhook payload. | `/var/run/act/workflow/event.json` |
+| `gitea.event_path`<br/>`github.event_path` | Path on the runner to the file containing the full event webhook payload. | `/home/runner/work/_temp/_github_workflow/event.json` |
 | `gitea.head_ref`<br/>`github.head_ref` | The source branch of a pull request. Only set for `pull_request` and `pull_request_target` events. | `feature-branch` |
 | `gitea.job`<br/>`github.job` | The `job_id` of the current job. | `build` |
 | `gitea.ref`<br/>`github.ref` | The fully-formed ref that triggered the workflow. | `refs/heads/main` |
 | `gitea.ref_name`<br/>`github.ref_name` | The short ref name. | `main` |
 | `gitea.ref_protected`<br/>`github.ref_protected` | `true` if branch protections are configured for the ref that triggered the workflow run. | `true` |
 | `gitea.ref_type`<br/>`github.ref_type` | The type of ref: `branch` or `tag`. | `branch` |
-| `gitea.path`<br/>`github.path` | Path on the runner to the file that sets system `PATH` variables from workflow commands. | `/var/run/act/workflow/pathcmd.txt` |
+| `gitea.path`<br/>`github.path` | Path on the runner to the file that sets system `PATH` variables from workflow commands. Unique to each step. | `/home/runner/work/_temp/_runner_file_commands/add_path_***` |
-| `gitea.repository`<br/>`github.repository` | The owner and repository name. | `owner/repo` |
+| `gitea.repository`<br/>`github.repository` | The owner and repository name. | `gitea/docs` |
-| `gitea.repository_owner`<br/>`github.repository_owner` | The repository owner's username. | `owner` |
+| `gitea.repository_owner`<br/>`github.repository_owner` | The repository owner's username. | `gitea` |
-| `gitea.repositoryUrl`<br/>`github.repositoryUrl` | The HTML URL to the repository. | `https://gitea.example.com/owner/repo` |
+| `gitea.repositoryUrl`<br/>`github.repositoryUrl` | The HTML URL to the repository. | `https://gitea.com/gitea/docs` |
-| `gitea.retention_days`<br/>`github.retention_days` | The number of days that artifacts are kept, empty when kept forever. | `90` |
+| `gitea.retention_days`<br/>`github.retention_days` | The number of days that workflow run logs and artifacts are kept. | `90` |
 | `gitea.run_id`<br/>`github.run_id` | A unique number for each workflow run within a repository. Does not change on re-run. | `1234` |
 | `gitea.run_number`<br/>`github.run_number` | A unique number for each run of a particular workflow. Starts at 1 and increments with each new run. | `42` |
 | `gitea.run_attempt`<br/>`github.run_attempt` | A unique number for each re-run attempt. Starts at 1 and increments with each re-run. | `1` |
 | `gitea.secret_source`<br/>`github.secret_source` | The source of a secret used in a workflow. Always `Actions` in Gitea. | `Actions` |
-| `gitea.server_url`<br/>`github.server_url` | The URL of the Gitea instance. | `https://gitea.example.com` |
+| `gitea.server_url`<br/>`github.server_url` | The URL of the Gitea instance. | `https://gitea.com` |
 | `gitea.sha`<br/>`github.sha` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
-| `gitea.token`<br/>`github.token` | A token to authenticate on behalf of the Gitea App installed on the repository. See [Token permissions](token-permissions.md). | `***` |
+| `gitea.token`<br/>`github.token` | A token to authenticate on behalf of the Gitea App installed on the repository. See [Token permissions](token-permissions.md). | `ghs_***` |
-| `gitea.triggering_actor`<br/>`github.triggering_actor` | The username of the user that initiated the workflow run. May differ from `actor` on re-runs. | `alice` |
+| `gitea.triggering_actor`<br/>`github.triggering_actor` | The username of the user that initiated the workflow run. May differ from `actor` on re-runs. | `silverwind` |
 | `gitea.workflow`<br/>`github.workflow` | The name of the workflow. If unnamed, the full path of the workflow file. | `CI` |
-| `gitea.workspace`<br/>`github.workspace` | The default working directory on the runner and the default location of your repository when using the `checkout` action. | `/workspace/owner/repo` |
+| `gitea.workspace`<br/>`github.workspace` | The default working directory on the runner and the default location of your repository when using the `checkout` action. | `/workspace/gitea/docs` |
 | `gitea.gitea_default_actions_url` | The default URL for downloading actions. Gitea-specific. | `https://github.com` |
 ### Event payload
@@ -138,11 +124,11 @@ These fields exist in almost every payload:
 | Name | Description | Example |
 |---|---|---|
 | `gitea.event.action` | The activity type. Only set for events that have activity types, see [supported events](faq.md#what-workflow-trigger-events-does-gitea-support). | `opened` |
-| `gitea.event.repository.full_name` | The owner and name of the repository. | `owner/repo` |
+| `gitea.event.repository.full_name` | The owner and name of the repository. | `gitea/docs` |
 | `gitea.event.repository.default_branch` | The default branch of the repository. | `main` |
 | `gitea.event.repository.private` | Whether the repository is private. | `false` |
-| `gitea.event.repository.html_url` | The HTML URL of the repository. | `https://gitea.example.com/owner/repo` |
+| `gitea.event.repository.html_url` | The HTML URL of the repository. | `https://gitea.com/gitea/docs` |
-| `gitea.event.sender.login` | The username of the user that triggered the event. Also available as `sender.username`. | `alice` |
+| `gitea.event.sender.login` | The username of the user that triggered the event. Also available as `sender.username`. | `silverwind` |
 The remaining fields are specific to one or a few events:
@@ -157,12 +143,12 @@ The remaining fields are specific to one or a few events:
 | `gitea.event.commits` | `push` | The commits contained in the push, each with `id`, `message`, `url`, `author`, `added`, `removed` and `modified`. | `[{...}]` |
 | `gitea.event.head_commit.message` | `push` | The message of the most recent commit of the push. | `fix: broken link` |
 | `gitea.event.total_commits` | `push` | The number of commits in the push. Gitea-specific. | `3` |
-| `gitea.event.compare_url` | `push` | The URL comparing `before` with `after`. GitHub names this field `compare`. | `https://gitea.example.com/owner/repo/compare/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2...f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5` |
+| `gitea.event.compare_url` | `push` | The URL comparing `before` with `after`. GitHub names this field `compare`. | `https://gitea.com/gitea/docs/compare/a1b2c3d...e5f6a1b` |
-| `gitea.event.pusher.login` | `push` | The username of the user that pushed. | `alice` |
+| `gitea.event.pusher.login` | `push` | The username of the user that pushed. | `silverwind` |
-| `gitea.event.forkee.full_name` | `fork` | The owner and name of the new fork. | `alice/repo` |
+| `gitea.event.forkee.full_name` | `fork` | The owner and name of the new fork. | `silverwind/docs` |
 | `gitea.event.page` | `gollum` | The name of the wiki page. | `Home` |
 | `gitea.event.number` | `issues`, `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The index of the issue or pull request. Not set for `issue_comment`, use `gitea.event.issue.number` there. | `386` |
-| `gitea.event.issue.number`<br/>`gitea.event.issue.title`<br/>`gitea.event.issue.body`<br/>`gitea.event.issue.state`<br/>`gitea.event.issue.labels`<br/>`gitea.event.issue.user.login` | `issues`, `issue_comment` | The issue the event happened on. | `Fix typo in README` |
+| `gitea.event.issue.number`<br/>`gitea.event.issue.title`<br/>`gitea.event.issue.body`<br/>`gitea.event.issue.state`<br/>`gitea.event.issue.labels`<br/>`gitea.event.issue.user.login` | `issues`, `issue_comment` | The issue the event happened on. | `Expand gitea.event in actions docs` |
 | `gitea.event.comment.body` | `issue_comment` | The body of the comment. | `LGTM` |
 | `gitea.event.is_pull` | `issue_comment` | Whether the comment was made on a pull request. Gitea-specific, GitHub sets `issue.pull_request` on the issue object instead. | `true` |
 | `gitea.event.pull_request.number`<br/>`gitea.event.pull_request.title`<br/>`gitea.event.pull_request.body`<br/>`gitea.event.pull_request.draft`<br/>`gitea.event.pull_request.merged`<br/>`gitea.event.pull_request.state`<br/>`gitea.event.pull_request.labels`<br/>`gitea.event.pull_request.user.login` | `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The pull request the event happened on. | `Add caching to CI` |
@@ -15,7 +15,7 @@ creating issues and pull requests. This will cut down on the initial back and fo
 of getting some clarifying details.
 It is currently not possible to provide generic issue/pull-request templates globally.
-Additionally, the New Issue page URL can be suffixed with `?title=Issue+Title&body=Issue+Text` and the form will be populated with those strings. Those strings will be used instead of the template if there is one. See [Pre-filling Issues and Pull Requests](prefill-issues-pull-requests.md) for all parameters.
+Additionally, the New Issue page URL can be suffixed with `?title=Issue+Title&body=Issue+Text` and the form will be populated with those strings. Those strings will be used instead of the template if there is one.
 ## File names
@@ -1,42 +0,0 @@
 ---
 date: "2026-10-17T00:00:00+00:00"
 slug: "prefill-issues-pull-requests"
 sidebar_position: 14
 ---
 # Pre-filling Issues and Pull Requests
 Links to the pages for creating issues and pull requests can pre-fill the form with query parameters.
 This lets you link users from another app, a README or a project board to a form that is already categorized.
 - New issue: `/{owner}/{repo}/issues/new?…`
 - New pull request: `/{owner}/{repo}/compare/{base}...{head}?…`
 For example, this link opens a new issue with a title, two labels and an assignee:
 ```
 https://gitea.example.com/owner/repo/issues/new?title=Dashboard+crashes&label=kind/bug,area/dashboard&assignee=alice
 ```
 ## Parameters
 | Parameter     | Value                                                                       |
 | ------------- | --------------------------------------------------------------------------- |
 | `title`       | Title                                                                       |
 | `body`        | Description                                                                 |
 | `label`       | Comma-separated label IDs or names                                          |
 | `labels`      | Alias of `label`                                                            |
 | `milestone`   | Milestone ID or name                                                        |
 | `project`     | Comma-separated project IDs or titles                                       |
 | `assignee`    | Comma-separated user IDs or usernames                                       |
 | `template`    | File name of the [template](issue-pull-request-templates.md) to use         |
 | `field:<id>`  | Value of the field with this `id` in a YAML template                        |
 IDs and names can be mixed and names are matched case-insensitively. Values that don't match anything in the repository are ignored.
 Labels include the organization's labels, and closed milestones and projects can be selected too.
 Milestones and projects are only offered to users who can write to issues or pull requests, so for other users these parameters have no effect.
 The values from the link take precedence over the title, description, labels and assignees of the template.
 When there are several issue templates to choose from, the parameters are passed through to the chosen one.
 On the compare page, any of these parameters also opens the pull request form directly, as `expand=1` does.
@@ -36,7 +36,6 @@ The following package managers are currently supported:
 | [RubyGems](usage/packages/rubygems.md) | Ruby | `gem`, `Bundler` |
 | [Swift](usage/packages/swift.md) | Swift | `swift` |
 | [Terraform](usage/packages/terraform.md) | - | `terraform` |
 | [Terraform Module](usage/packages/terraform-module.md) | - | `terraform`, `terragrunt` |
 | [Vagrant](usage/packages/vagrant.md) | - | `vagrant` |
 **The following paragraphs only apply if Packages are not globally disabled!**
@@ -56,11 +55,11 @@ and shows a link to the repository on the package site (as well as a link to the
 | Package owner type | User | Organization |
 |--------------------|------|--------------|
 | **read** access    | public, if user is public too; otherwise for this user only | public, if org is public, otherwise for org members only |
-| **write** access   | owner only | members of a team with write access to packages |
+| **write** access   | owner only | org members with admin or write access to the org |
 Please note, that your respective package manager needs to have a [personal access token](development/api-usage.md#authentication) with the permissions `package` set to either Read or Read & Write to download and publish packages respectively.
-The packages permission of an organization team applies to all packages of the organization, regardless of the repositories assigned to the team.
+N.B.: These access restrictions are [subject to change](https://github.com/go-gitea/gitea/issues/19270), where more finegrained control will be added via a dedicated organization team permission.
 ## Create or upload a package
@@ -1,170 +0,0 @@
 ---
 date: "2026-06-09T00:00:00+00:00"
 slug: "terraform-module"
 sidebar_position: 119
 ---
 # Terraform Module Registry
 Publish [Terraform](https://www.terraform.io/) modules for your user or organization and use them
 from Terraform or Terragrunt. The registry implements the
 [HashiCorp module registry protocol](https://developer.hashicorp.com/terraform/internals/module-registry-protocol),
 so modules are referenced with the usual `HOST/NAMESPACE/NAME/PROVIDER` address.
 ## Requirements
 - The [Terraform CLI](https://developer.hashicorp.com/terraform/install) or
  [Terragrunt](https://terragrunt.gruntwork.io/).
 - **Your Gitea instance must be served over HTTPS with a valid certificate.**
  Terraform and Terragrunt only perform module registry discovery over HTTPS and reject
  plain HTTP — including `http://localhost`. This is a requirement of the protocol, not of Gitea.
 A module is addressed by three segments:
 | Segment     | Meaning                                                        |
 | ----------- | ------------------------------------------------------------- |
 | `namespace` | The owner of the module: a Gitea user or organization name. It must follow the same rules as `name`, so owners with a `.` in their name cannot publish modules. |
 | `name`      | The module name. Letters, digits, `-` and `_`, starting and ending with a letter or digit, up to 64 characters. |
 | `provider`  | The main provider the module targets, e.g. `aws`. Lowercase letters and digits, up to 64 characters. |
 Versions follow [semantic versioning](https://semver.org/) and are stored in canonical form: a
 leading `v` is dropped and missing segments are padded, so `v1.2.3` and `1.2.3` address the same
 version, and `1.2` becomes `1.2.0`.
 ## Packaging a module
 A module is published as a single `.tar.gz` archive, stored and served exactly as uploaded. The
 module's `.tf` files must therefore be at the **archive root**. A source tarball downloaded from a Git
 host wraps everything in a `repository-version/` directory and is rejected — repackage the module
 directory's contents instead:
 ```shell
 tar -czf vpc-1.0.0.tar.gz -C path/to/module .
 ```
 The root module's inputs, outputs, providers and `README` are shown on the package page. Each
 submodule found under `modules/<name>` is listed with its source address and links to its own page,
 which shows the install snippet for that submodule along with its inputs, outputs, providers and
 `README`. Only one level is indexed, so `modules/<name>/<nested>` is not listed. Anything else,
 including `examples/`, is kept in the archive but is not indexed. A module that is only a collection of
 submodules, with no root module, is also accepted. Files in JSON syntax (`.tf.json`) are accepted too,
 but only `.tf` files are indexed.
 ## Authentication
 Create a [personal access token](development/api-usage.md#authentication) with the `read:package` scope to download
 private modules, and `write:package` to publish or delete them. Add it to your Terraform CLI
 configuration file (`~/.terraformrc` or `%APPDATA%/terraform.rc`):
 ```hcl
 credentials "gitea.example.com" {
  token = "<your token>"
 }
 ```
 Modules owned by a public user or organization can be downloaded without a token.
 ## Publishing a module
 Upload an archive with a `PUT` request, sending the file as the raw request body. Use
 `curl --upload-file` rather than `--data-binary`: the latter sends a form content type that
 the registry will not accept as an archive.
 ```shell
 curl --user "your_username:your_token" \
  --upload-file vpc-1.0.0.tar.gz \
  https://gitea.example.com/api/packages/-/terraform/modules/{namespace}/{name}/{provider}/{version}
 ```
 | Parameter   | Description                            |
 | ----------- | -------------------------------------- |
 | `namespace` | The owner (user or organization).      |
 | `name`      | The module name.                       |
 | `provider`  | The provider the module targets.       |
 | `version`   | The module version (semver).           |
 For example, to publish version `1.0.0` of the `vpc` module for the `aws` provider under the `acme`
 organization:
 ```shell
 curl --user "your_username:your_token" \
  --upload-file vpc-1.0.0.tar.gz \
  https://gitea.example.com/api/packages/-/terraform/modules/acme/vpc/aws/1.0.0
 ```
 A successful upload returns `201 Created`. Published versions are immutable: uploading a version that
 already exists returns `409 Conflict`. To replace a version, delete it first.
 ## Linking a module to a repository
 A module always lives in a user or organization's package space — its namespace is that user or
 organization, never a repository, because the registry address (`HOST/NAMESPACE/NAME/PROVIDER`) has no
 repository segment. You cannot publish "into" a repository. Instead, a repository link is a display
 association that surfaces the module on a repository's **Packages** tab. The workflow is:
 1. **Publish** the module to the user or organization namespace, exactly as shown in
   [Publishing a module](#publishing-a-module).
 2. **Link** the package to a repository owned by that same user or organization: open the package,
   go to its **Settings**, and select the repository (or use the
   `POST /api/v1/packages/{owner}/terraform-module/{name}%2F{provider}/-/link/{repo}` API).
 The link applies to the whole module — all of its versions, including ones published later — and can
 be changed or removed at any time. It only affects where the module is listed in the UI; the address
 used to consume it is unchanged (still `HOST/NAMESPACE/NAME/PROVIDER`, with no repository in it).
 ## Consuming a module
 Reference the module by its registry address. With Terraform:
 ```hcl
 module "vpc" {
  source  = "gitea.example.com/acme/vpc/aws"
  version = "~> 1.0"
 }
 ```
 To use a submodule, append its path with the standard `//` separator:
 ```hcl
 module "network" {
  source  = "gitea.example.com/acme/infra/google//modules/network"
  version = "~> 1.0"
 }
 ```
 With Terragrunt, use the `tfr://` scheme and pass the version as a query parameter:
 ```hcl
 terraform {
  source = "tfr://gitea.example.com/acme/vpc/aws?version=1.0.0"
 }
 ```
 `terraform init` (or `terragrunt init`) resolves the address through the service discovery document
 at `https://gitea.example.com/.well-known/terraform.json` and downloads the matching version.
 ## Deleting a version
 ```shell
 curl --user "your_username:your_token" \
  --request DELETE \
  https://gitea.example.com/api/packages/-/terraform/modules/acme/vpc/aws/1.0.0
 ```
 A successful delete returns `204 No Content`. This requires the `write:package` scope. There is no
 separate deprecation flow — deleting a version removes it from the registry.
 ## Limits
 The stored archive is bounded by the instance-wide package limits (`LIMIT_SIZE_TERRAFORM_MODULE` and
 `LIMIT_TOTAL_OWNER_SIZE`) set by your Gitea administrator; see the
 [configuration cheat sheet](../../administration/config-cheat-sheet.md#packages-packages).
 Independently of those settings, an archive may not exceed **32 MiB decompressed**. The registry
 reads the whole archive to index it, and stops with `413 Request Entity Too Large` past that ceiling,
 so raising `LIMIT_SIZE_TERRAFORM_MODULE` above 32 MiB does not allow larger modules. Real modules are
 kilobyte-scale, so this only affects archives carrying unrelated payloads.
 A `README` larger than **1 MiB**, of the root module or of a submodule, is not shown on the package
 page. The module is still accepted and the file stays in the archive.
@@ -1,9 +0,0 @@
 {
  "label": "Projects",
  "position": 60,
  "link": {
    "type": "generated-index",
    "slug": "/usage/projects",
    "description": "Plan and track work with project boards"
  }
 }
@@ -1,82 +0,0 @@
 ---
 date: "2025-11-25T18:58:22Z"
 slug: "project-workflows"
 sidebar_position: 1
 description: "Automate project boards with event-driven filters and actions."
 ---
 # Project Workflows
 Project workflows automate a project board. When an issue or pull request in the project triggers an event, each enabled workflow for that event checks its filters and applies its actions. Workflows run in Gitea and need no runner.
 ## Edit workflows
 1. Open a project and select **Workflows**.
 2. Select an event in the sidebar.
 3. Set filters and actions, then select **Save**. To change an existing workflow, select **Edit** first.
 An event can have several workflows. **Clone** copies the selected workflow so you can adapt it to other items. **Disable** pauses a workflow and keeps its configuration. **Remove** deletes it.
 ## Events
 | Event | Runs when | Filters | Actions |
 | --- | --- | --- | --- |
 | Item added to project | An item is added to the project or created in it | Apply to, labels | Move to column, labels, issue state |
 | Item removed from project | An item is removed from the project | Apply to, labels | Labels, issue state |
 | Item reopened | An item is reopened | Apply to, labels | Move to column, labels |
 | Item closed | An item is closed | Apply to, labels | Move to column, labels |
 | Item column changed | An item moves to another column | Apply to, columns, labels | Labels, issue state |
 | Code changes requested | An official reviewer requests changes on a pull request | Labels | Move to column, labels |
 | Code review approved | An official reviewer approves a pull request | Labels | Move to column, labels |
 | Pull request merged | A pull request is merged | Labels | Move to column, labels |
 ## Filters
 A workflow without filters runs for every item.
 - **Apply to**: issues, pull requests, or both.
 - **When moved from column**, **When moved to column**: the column the item left or entered.
 - **Only if it has labels**: the item must have all selected labels.
 ## Actions
 A workflow needs at least one action. Actions run in this order:
 1. **Move to column**: moves the item to a column.
 2. **Add labels**, **Remove labels**: changes the item's labels.
 3. **Issue state**: closes or reopens the item. Workflows never reopen pull requests.
 Workflow changes appear in the timeline as "Project workflow" followed by the event, and don't trigger other workflows. Workflows don't run in closed projects or for items in archived repositories.
 ## Permissions
 Anyone who can read a project can view its workflows. Managing them requires write access to the project and:
 - Repository project: write access to the repository's issues and pull requests.
 - Organization project: organization owner or site administrator.
 - User project: the project's owner.
 Access tokens limited to public repositories can't manage workflows for organization or user projects. Workflows apply their actions regardless of who triggered the event.
 ## API
 Manage workflows under the project routes of a repository (`/repos/{owner}/{repo}/projects/{id}`), an organization (`/orgs/{org}/projects/{id}`) or the authenticated user (`/user/projects/{id}`):
 | Method | Path | Purpose |
 | --- | --- | --- |
 | `GET` | `.../workflows` | List workflows |
 | `GET` | `.../workflows/{workflow_id}` | Get a workflow |
 | `POST` | `.../workflows` | Create a workflow |
 | `PATCH` | `.../workflows/{workflow_id}` | Edit a workflow, omitted fields stay unchanged |
 | `DELETE` | `.../workflows/{workflow_id}` | Delete a workflow |
 A workflow has an `event` (`item_added_to_project`, `item_removed_from_project`, `item_reopened`, `item_closed`, `item_column_changed`, `code_changes_requested`, `code_review_approved` or `pull_request_merged`), an `enabled` flag, `filters` (`issue_type`, `source_column_id`, `target_column_id`, `label_ids`) and `actions` (`column_id`, `add_label_ids`, `remove_label_ids`, `issue_state`). Each event accepts only the filters and actions listed in [Events](#events).
 ## Example
 To route new bug reports to triage, create a workflow for **Item added to project**:
 - **Apply to**: Issues only
 - **Only if it has labels**: `bug`
 - **Move to column**: Triage
 - **Add labels**: `needs-triage`
@@ -9,36 +9,25 @@ aliases:
 # Code Owners
-Gitea reads the first CODEOWNERS file found at these locations, in order:
+Gitea maintains code owner files. It looks for it in the following locations in this order:
 - `./CODEOWNERS`
 - `./docs/CODEOWNERS`
 - `./.gitea/CODEOWNERS`
-Pull requests use the base branch's rules. File views show owners from the commit
+And stops at the first found file.
 being viewed, including when browsing a branch, tag, or historical commit.
-## Patterns and owners
+File format: `<regexp rule> <@user or @org/team> [@user or @org/team]...`
-Each rule contains a pattern followed by users or organization teams.
+Regexp specified in golang Regex format.
-
+Regexp can start with `!` for negative rules - match all files except specified.
 Patterns starting with `*` or containing `/*` are parsed as glob expressions.
 General patterns are parsed as regular expressions.
 A leading `!` inverts a match.
 Special rule characters like space, backslash and `#` must be escaped with a backslash.
 When using regexp, since backslash needs to be escaped in rule level, literal dot should be written as  `\\.`
 Example file:
-```text
+```bash
-*.js @alice @bob       # This is an inline comment
+.*\\.go @user1 @user2 # This is comment
 doc/*.md @charles      # Patterns starting with "*" or containing "/*" are parsed as glob
 src/**/db*.py @david   # Use "**" to match any-level sub directories
 .*\\.go @user1 @user2   # General patterns are parsed as regexp
 test\\..*\\.js @user3   # !!! Do remeber: NOT "test.*.js", only regexp can be used for such cases
 # Comment too
 # You can assigning code owning for users or teams
 frontend/src/.*\\.js @org1/team1 @org1/team2 @user3
@@ -53,69 +42,24 @@ docs/(aws|google|azure)/[^/]*\\.(md|txt) @user8 @org1/team4
 Code owners listed in this file will automatically be requested to review pull requests
 that modify files matching at least one corresponding rule.
-## Sections
+### Escaping
-A section heading can supply default owners for the rules that follow it:
+You can escape characters `#`, ` ` (space) and `\` with `\`, like:
 ```text
 [Documentation] @org1/team-doc
 *.md
 README.md @alice
 [Frontend] @bob
 *.js
 ```
 Owners on a rule replace the section's default owners. Section names are
 case-insensitive; repeated headings belong to the same section. For each file, the
 last matching rule in each named section applies. Matching rules outside named
 sections retain Gitea's existing behavior: they all apply.
 ## Review request annotations
 Use `## review-request=true` or `## review-request=false` to control automatic
 review requests. A line annotation overrides a section annotation, which overrides
 the global value. When none is set, individual code owners receive automatic review
 requests only if they watch the repository and include pull requests in their watch
 preferences. Team-level requests are enabled by default. An explicit `true` requests
 a review regardless of the individual owner's watch preferences; `false` disables
 automatic requests for the rule.
 ```text
 ## review-request=false # global default for following rules
 *.js @alice ## review-request=true # only this rule
 [Documentation] @org1/team-doc ## review-request=true
 *.md
 private/* @bob ## review-request=false
 ```
 A standalone annotation changes the global default for subsequent rules.
 Annotations on section headings apply until the next heading. Ordinary comments
 start with `#`, including comments after annotations.
 Disabling review requests keeps code owners visible when viewing a file and
 does not waive approvals required by branch protection.
 ## Escaping
 You need to escape characters `#`, ` ` (space) and `\` with backslash `\`, e.g.:
 ```text
 dir/with\#hashtag @user1
 path\ with\ space @user2
 path/with\\backslash @user3
 ```
-Some regexp characters (`.+*?()|[]{}^$\`) should be escaped with `\\`, e.g.:
+Some character (`.+*?()|[]{}^$\`) should be escaped with `\\` inside regexp, like:
 ```
 path/\\.with\\.dots
 path/with\\+plus
 ```
-## Branch Protection Rules
+### Branch Protection Rules
 When setting up branch protection rules, you may choose to enforce code owner approval of
 modified files. This will block a PR from being merged until at least one code owner
@@ -123,7 +67,7 @@ has given approval for every applicable rule listed in the `CODEOWNERS` file.
 For example, say you have the following `CODEOWNERS` file:
-```text
+```bash
 .*\\.go @Bob
 .*\\.md @Sally @Chris
 migrations/.* @Alice
@@ -1,64 +0,0 @@
 ---
 date: "2018-06-24:00:00+02:00"
 slug: "api-usage"
 sidebar_position: 40
 aliases:
  - /zh-cn/api-usage
 ---
 # API 使用指南
 ## 开启/配置 API 访问
 通常情况下， `ENABLE_SWAGGER` 默认开启并且参数 `MAX_RESPONSE_ITEMS` 默认为 50。您可以从 [Config Cheat Sheet](../administration/config-cheat-sheet.md) 中获取更多配置相关信息。
 <a id="authentication"></a>
 ## 通过 API 认证
 Gitea 支持以下几种 API 认证方式：
 - HTTP basic authentication 方式
 - 通过指定 `token=...` URL 查询参数方式
 - 通过指定 `access_token=...` URL 查询参数方式
 - 通过指定 `Authorization: token ...` HTTP header 方式
 以上提及的认证方法接受相同的 apiKey token 类型，您可以在编码时通过查阅代码更好地理解这一点。
 Gitea 调用解析查询参数以及头部信息来获取 token 的代码可以在 [modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47) 中找到。
 您可以通过您的 gitea web 界面来创建 apiKey token：
 `Settings | Applications | Generate New Token`.
 ### 关于 `Authorization:` header
 由于一些历史原因，Gitea 需要在 header 的 apiKey token 里引入前缀 `token`，类似于如下形式：
 ```
 Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675
 ```
 以 `curl` 命令为例，它会以如下形式携带在请求中：
 ```
 curl "http://localhost:4000/api/v1/repos/test1/test1/issues" \
    -H "accept: application/json" \
    -H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \
    -H "Content-Type: application/json" -d "{ \"body\": \"testing\", \"title\": \"test 20\"}" -i
 ```
 正如上例所示，您也可以在 GET 请求中使用同一个 token 并以 `token=` 的查询参数形式携带 token 来进行认证。
 ## 通过 API 列出您发布的令牌
 `/users/:name/tokens` 是一个特殊的接口，需要您使用 basic authentication 进行认证，具体原因在 issue 中
 [#3842](https://github.com/go-gitea/gitea/issues/3842#issuecomment-397743346) 有所提及，使用方法如下所示：
 ### 使用 Basic authentication 认证
 ```
 $ curl --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens
 [{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}]
 ```
 ## 使用 Sudo 方式请求 API
 此 API 允许管理员借用其他用户身份进行 API 请求。只需在请求中指定查询参数 `sudo=` 或是指定 header 中的 `Sudo:` 为需要使用的用户 username 即可。
@@ -1,218 +0,0 @@
 ---
 date: "2016-12-01T16:00:00+02:00"
 slug: "install-from-source"
 sidebar_position: 30
 aliases:
  - /zh-cn/install-from-source
 ---
 # 使用源代码安装
 你需要 [安装 Go](https://golang.google.cn/doc/install) 并正确设置 Go 环境。特别的，建议设置`$GOPATH`环境变量，并将 Go 的二进制目录或目录`${GOPATH//://bin:}/bin`添加到`$PATH`中。请参阅 Go 百科上关于 [GOPATH](https://github.com/golang/go/wiki/GOPATH) 的词条。
 接下来，[安装 Node.js 和 npm](https://nodejs.org/zh-cn/download/)， 这是构建 JavaScript 和 CSS 文件所需的。最低支持的 Node.js 版本是 @minNodeVersion@，建议使用最新的 LTS 版本。
 **注意**：需要 Go 版本 @minGoVersion@ 或更高版本。不过，建议获取与我们的持续集成（continuous integration, CI）相同的版本，请参阅在 [Hacking on Gitea](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md) 中给出的建议。
 ## 下载
 首先，我们需要获取源码。由于引入了 Go 模块，最简单的方法是直接使用 Git，因为我们不再需要在 GOPATH 内构建 Gitea。
 ```bash
 git clone https://github.com/go-gitea/gitea
 ```
 （之前的版本中建议使用 `go get`，但现在不再需要。）
 你可以选择编译和安装的版本，当前有多个选择。`main` 分支代表当前的开发版本。如果你想编译 `main` 版本，你可以直接跳到 [构建](#构建) 部分。
 如果你想编译带有标签的发行版本，可以使用以下命令签出：
 ```bash
 git branch -a
 git checkout @sourceBranch@
 ```
 要验证一个拉取请求（Pull Request, PR），要先启用新的分支（其中 `xyz` 是 PR 的 ID；例如，对于 [#2663](https://github.com/go-gitea/gitea/pull/2663)，ID 是 `2663 `）：
 ```bash
 git fetch origin pull/xyz/head:pr-xyz
 ```
 要以指定发行版本（如 @sourceVersion@ ）的源代码来构建 Gitea，可执行以下命令列出可用的版本并选择某个版本签出。
 使用以下命令列出可用的版本：
 ```bash
 git tag -l
 git checkout @sourceVersion@  # or git checkout pr-xyz
 ```
 ## 构建
 要从源代码进行构建，系统必须预先安装以下程序：
 - `go` @minGoVersion@ 或更高版本，请参阅 [这里](https://go.dev/dl/)
 - `node` @minNodeVersion@ 或更高版本，并且安装 `npm`, 请参阅 [这里](https://nodejs.org/zh-cn/download/)
 - `make`, 请参阅 [这里](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md)
 为了尽可能简化编译过程，提供了各种 [make 任务](https://github.com/go-gitea/gitea/blob/main/Makefile)。
 根据你的构建需求，以下 tags 可以使用：
 - `bindata`: 构建一个单一的整体二进制文件，包含所有资源。适用于构建生产环境版本。
 - `sqlite sqlite_unlock_notify`: 启用对 [SQLite3](https://sqlite.org/) 数据库的支持。仅建议在少数人使用时使用这个模式。
 - `pam`: 启用对 PAM（ Linux 可插拔认证模块）的支持。可用于对本地用户进行身份验证或扩展身份验证到 PAM 可用的方法。
 - `gogit`：（实验性功能）使用 go-git 变体的 Git 命令。
 将所有资源（JS/CSS/模板等）打包到二进制文件中。在生产环境部署时，使用`bindata`构建标签是必需的。在开发/测试 Gitea 或能够明确分离资源时，可以不用`bindata`。
 要包含所有资源，请使用 `bindata` 标签：
 ```bash
 TAGS="bindata" make build
 ```
 在我们的持续集成系统的默认发行版中，构建标签为：`TAGS="bindata sqlite sqlite_unlock_notify"`。因此，从源码构建的最简单、推荐方式是：
 ```bash
 TAGS="bindata sqlite sqlite_unlock_notify" make build
 ```
 `build`目标分为两个子目标：
 - `make backend` 需要 [Go @minGoVersion@](https://golang.google.cn/doc/install) 或更高版本。
 - `make frontend` 需要 [Node.js @minNodeVersion@](https://nodejs.org/zh-cn/download/) 或更高版本。
 如果存在预构建的前端文件，可以仅构建后端：
 ```bash
 TAGS="bindata" make backend
 ```
 ## 测试
 按照上述步骤完成后，工作目录中将会有一个`gitea`二进制文件。可以从该目录进行测试，或将其移动到带有测试数据的目录中。当手动从命令行启动 Gitea 时，可以通过按下`Ctrl + C`来停止程序。
 ```bash
 ./gitea web
 ```
 ## 更改默认路径
 Gitea 将从`CustomPath`中查找许多信息。默认的，这会在运行 Gitea 时当前工作目录下的`custom/`目录中（译者案：即`$PATH_TO_YOUR_GITEA$/custom/`）。它还将在`$(CustomPath)/conf/app.ini`中查找其配置文件`CustomConf`，并将当前工作目录用作一些可配置值的相对基本路径`AppWorkPath`。最后，静态文件将从默认为 `AppWorkPath`的`StaticRootPath`提供。
 尽管在开发时这些值很有用，但可能与下游用户的偏好冲突。
 一种选择是使用脚本文件来隐藏`gitea`二进制文件，并在运行 Gitea 之前创建适当的环境。然而，在构建时，可以使用`make`的`LDFLAGS`环境变量来更改这些默认值。适当的设置如下：
 - 要设置`CustomPath`，请使用`LDFLAGS="-X \"code.gitea.io/gitea/modules/setting.CustomPath=custom-path\""`
 - 对于`CustomConf`，应该使用`-X \"code.gitea.io/gitea/modules/setting.CustomConf=conf.ini\"`
 - 对于`AppWorkPath`，应该使用`-X \"code.gitea.io/gitea/modules/setting.AppWorkPath=working-path\"`
 - 对于`StaticRootPath`，应该使用`-X \"code.gitea.io/gitea/modules/setting.StaticRootPath=static-root-path\"`
 - 要更改默认的 PID 文件位置，请使用`-X \"code.gitea.io/gitea/cmd.PIDFile=/run/gitea.pid\"`
 将这些字符串与其前导的`-X`添加到`LDFLAGS`变量中，并像上面那样使用适当的`TAGS`运行`make build`。
 运行`gitea help`将允许您查看配置的`gitea`设置。
 ## 交叉编译
 `go`编译器工具链支持将代码交叉编译到不同的目标架构上。请参考[`GOOS`和`GOARCH`环境变量](https://go.dev/doc/install/source#environment) 以获取支持的目标列表。如果您想为性能较弱的系统（如树莓派）构建 Gitea，交叉编译非常有用。
 要使用构建标签（`TAGS`）进行交叉编译 Gitea，您还需要一个 C 交叉编译器，该编译器的目标架构与`GOOS`和`GOARCH`变量选择的架构相同。例如，要为 Linux ARM64（`GOOS=linux`和`GOARCH=arm64`）进行交叉编译，您需要`aarch64-unknown-linux-gnu-gcc`交叉编译器。这是因为 Gitea 构建标签使用了`cgo`的外部函数接口（FFI）。
 在没有任何标签的情况下，交叉编译的 Gitea 为 Linux ARM64 版本：
 ```
 GOOS=linux GOARCH=arm64 make build
 ```
 要交叉编译 Linux ARM64 下的 Gitea，这是推荐的构建标签：
 ```
 CC=aarch64-unknown-linux-gnu-gcc GOOS=linux GOARCH=arm64 TAGS="bindata sqlite sqlite_unlock_notify" make build
 ```
 根据您的目标架构，适当替换`CC`、`GOOS`和`GOARCH`。
 有时您需要构建一个静态编译的镜像。为此，您需要添加以下内容：
 ```
 LDFLAGS="-linkmode external -extldflags '-static' $LDFLAGS" TAGS="netgo osusergo $TAGS" make build
 ```
 这可以与上述的`CC`、`GOOS`和`GOARCH`结合使用。
 ### 添加 bash/zsh 自动补全（从 1.19 版本起）
 在[`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete)中可以找到一个启用 bash 自动补全的脚本。您可以根据需要进行修改，并在您的 `.bashrc` 中使用 `source` 命令加载该脚本，或者将其复制到 `/usr/share/bash-completion/completions/gitea`。
 类似地，可以在[`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete)中找到一个用于 zsh 自动补全的脚本。您可以将其复制到 `/usr/share/zsh/_gitea`，或者在您的 `.zshrc` 中使用 `source` 命令加载该脚本。
 可能需要你根据具体情况进一步改进这些脚本。
 ## 在 Linux 上使用 Zig 进行编译或交叉编译
 请按照 [Zig 的入门指南](https://ziglang.org/learn/getting-started/#installing-zig) 安装 Zig。
 - 编译 (Linux ➝ Linux)
 ```sh
 CC="zig cc -target x86_64-linux-gnu" \
 CGO_ENABLED=1 \
 CGO_CFLAGS="-O2 -g -pthread" \
 CGO_LDFLAGS="-linkmode=external -v"
 GOOS=linux \
 GOARCH=amd64 \
 TAGS="bindata sqlite sqlite_unlock_notify" \
 make build
 ```
 - 交叉编译 (Linux ➝ Windows)
 ```sh
 CC="zig cc -target x86_64-windows-gnu" \
 CGO_ENABLED=1 \
 CGO_CFLAGS="-O2 -g -pthread" \
 GOOS=windows \
 GOARCH=amd64 \
 TAGS="bindata sqlite sqlite_unlock_notify" \
 make build
 ```
 ## 在 Windows 上使用 Zig 进行编译或交叉编译
 使用`GIT BASH`编译。
 - 编译 (Windows ➝ Windows)
 ```sh
 CC="zig cc -target x86_64-windows-gnu" \
 CGO_ENABLED=1 \
 CGO_CFLAGS="-O2 -g -pthread" \
 GOOS=windows \
 GOARCH=amd64 \
 TAGS="bindata sqlite sqlite_unlock_notify" \
 make build
 ```
 - 交叉编译 (Windows ➝ Linux)
 ```sh
 CC="zig cc -target x86_64-linux-gnu" \
 CGO_ENABLED=1 \
 CGO_CFLAGS="-O2 -g -pthread" \
 CGO_LDFLAGS="-linkmode=external -v"
 GOOS=linux \
 GOARCH=amd64 \
 TAGS="bindata sqlite sqlite_unlock_notify" \
 make build
 ```
 ## Source Map
 默认情况下，gitea 会为前端文件生成精简的 Source Map 以节省空间。 这可以通过“ENABLE_SOURCEMAP”环境变量进行控制：
 - `ENABLE_SOURCEMAP=true` 生成所有 Source Map，这是开发版本的默认设置
 - `ENABLE_SOURCEMAP=reduced` 生成有限的 Source Map，这是生产版本的默认设置
 - `ENABLE_SOURCEMAP=false` 不生成 Source Map
@@ -1,94 +0,0 @@
 ---
 date: "2023-05-24T15:00:00+08:00"
 slug: "comparison"
 sidebar_position: 15
 ---
 # 与GitHub Actions的对比
 Gitea Actions旨在与GitHub Actions兼容，差异如下。
 ## 额外功能
 <a id="absolute-action-urls"></a>
 ### Action URL绝对路径
 `uses:`支持指向任意Git托管平台的绝对URL，例如`uses: https://gitea.com/actions/checkout@v4`。
 <a id="action-prefixes"></a>
 ### Action前缀
 `uses:`支持以下前缀：
 - `self:`引用您自己的Gitea实例，例如`uses: self:owner/repo@v1`或`uses: self:owner/repo/.gitea/workflows/build.yml@v1`
 - `builtin:`运行Gitea Runner内置的Action，无需下载，也不依赖Node.js，例如`uses: builtin:checkout`
 ### 使用Go编写Actions
 请参阅[创建Go Actions](https://blog.gitea.com/creating-go-actions/)。
 ### 支持非标准的调度语法 @yearly, @monthly, @weekly, @daily, @hourly
 `schedule`还支持`@yearly`、`@monthly`、`@weekly`、`@daily`和`@hourly`，而[GitHub不支持](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule)。
 ## 不支持的工作流语法
 ### `jobs.<job_id>.environment`
 [`jobs.<job_id>.environment`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment)会被忽略。
 ### 复杂的`runs-on`
 [`runs-on`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)支持：
 - 静态字符串：`runs-on: self-hosted`
 - 标签数组：`runs-on: [linux, self-hosted]`
 - 字符串表达式：`runs-on: ${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}`
 - 包含表达式的数组：`runs-on: [linux, "${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}"]`
 ## 缺失的功能
 ### 软件包仓库授权
 `GITEA_TOKEN`无法发布到其所属仓库的软件包注册表，例如无法推送OCI镜像。
 请改用个人访问令牌，参见[此问题](https://github.com/go-gitea/gitea/issues/23642#issuecomment-2119876692)。
 ### 问题匹配器
 [问题匹配器](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md)会被忽略。
 ### 为错误创建注释
 [错误注释](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error)会被忽略。
 ### 表达式
 [表达式](https://docs.github.com/en/actions/learn-github-actions/expressions)支持GitHub的标准函数和上下文。
 ## 缺失的UI功能
 ### 预处理和后处理步骤
 预处理和后处理步骤在Job日志中没有单独的区块。
 ### 服务步骤
 服务步骤在Job日志中没有单独的区块。
 ## 不一样的行为
 ### `permissions`和`jobs.<job_id>.permissions`
 `permissions`和`jobs.<job_id>.permissions`控制`GITEA_TOKEN`的权限，该权限受仓库和所有者设置的限制，并在fork拉取请求和跨仓库访问时受到进一步限制。
 不支持`statuses`、`checks`、`deployments`、`security-events`和`pages`等GitHub专有的权限范围，而Gitea额外提供了`code`、`releases`、`wiki`和`projects`。`id-token`与GitHub相同，请参阅[OpenID Connect](openid-connect.md)。
 请参阅[Actions Job令牌权限](token-permissions.md)。
 ### 下载Actions
 未指定主机的Actions（如`uses: actions/checkout@v4`）会从`https://github.com`下载，当`[actions].DEFAULT_ACTIONS_URL`为`self`时则从您自己的实例下载。
 请参阅[配置备忘单](../../administration/config-cheat-sheet.md#actions-actions)。
 其他来源请参阅[Action URL绝对路径](#absolute-action-urls)和[Action前缀](#action-prefixes)。
 ### 上下文可用性
 不检查[上下文可用性](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability)，因此`env`等上下文可以在更多地方使用。
@@ -1,63 +0,0 @@
 ---
 date: "2026-08-23T00:00:00+00:00"
 slug: "openid-connect"
 sidebar_position: 40
 ---
 # OpenID Connect
 Job可以请求短期有效的OpenID Connect（OIDC）令牌来登录云服务商和其他服务，无需存储长期有效的密钥。这些令牌采用GitHub Actions的格式，因此`aws-actions/configure-aws-credentials`、`google-github-actions/auth`和`azure/login`等Action无需修改即可使用。
 <a id="trusting-gitea"></a>
 ## 信任Gitea
 在服务中将Gitea添加为OIDC身份提供方：
 - Issuer：`<ROOT_URL>/api/actions/oidc`
 - Audience：`<ROOT_URL>/<owner>`，除非工作流请求了其他值
 然后通过[`sub`声明](#claims)上的条件限制哪些工作流可以登录。
 Gitea使用其在`<APP_DATA_PATH>/jwt/actions_oidc.pem`创建的密钥签名令牌。负载均衡器后的多个实例必须共享此文件。
 <a id="requesting-a-token"></a>
 ## 请求令牌
 为工作流或Job授予`id-token`权限：
 ```yaml
 permissions:
  id-token: write
 ```
 默认权限从不包含此权限，来自fork拉取请求的Job也永远无法获得。所有者和仓库可以通过[最大令牌权限](token-permissions.md#maximum-token-permissions-clamping)禁用它。
 上述Action会自行请求令牌。在脚本中，请使用`ACTIONS_ID_TOKEN_REQUEST_URL`和`ACTIONS_ID_TOKEN_REQUEST_TOKEN`：
 ```shell
 curl --fail --silent --show-error \
  --header "Authorization: Bearer ${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" \
  "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=my-service"
 ```
 令牌位于响应的`value`字段中，五分钟后过期。
 <a id="claims"></a>
 ## 声明
 `sub`声明包含所有者和仓库的名称及ID，因此重命名或重新创建的仓库无法匹配已有的信任策略：
 ```text
 repo:<owner>@<owner-id>/<repo>@<repo-id>:ref:<ref>
 repo:<owner>@<owner-id>/<repo>@<repo-id>:pull_request
 ```
 `pull_request`事件使用第二种格式，其他所有事件（包括`pull_request_target`）使用第一种。
 其他声明与GitHub相同，例如`repository`、`ref`、`sha`、`workflow_ref`和`job_workflow_ref`。位于`<ROOT_URL>/api/actions/oidc/.well-known/openid-configuration`的发现文档列出了所有声明。
 与GitHub Actions的区别：
 - 没有`environment`声明。
 - 拉取请求的运行使用`refs/pull/<index>/head`及其提交，而不是合并引用和合并提交。
 - `run_number`按仓库计数，而不是按工作流计数。
@@ -1,131 +0,0 @@
 ---
 date: "2023-05-24T15:00:00+08:00"
 slug: "quickstart"
 sidebar_position: 10
 ---
 # 快速入门
 本页面将指导您使用Gitea Actions的过程。
 ## 设置Gitea
 首先，您需要一个Gitea实例。
 您可以按照[文档](installation/from-package.md) 来设置一个新实例或升级现有实例。
 无论您如何安装或运行Gitea，只要版本号是1.19.0或更高即可。
 从1.21.0开始，默认情况下，Actions是启用的。如果您正在使用1.21.0之前的版本，您需要将以下内容添加到配置文件中以启用它：
 ```ini
 [actions]
 ENABLED=true
 ```
 如果您想了解更多信息或在配置过程中遇到任何问题，请参考[配置速查表](../../administration/config-cheat-sheet.md#actions-actions)。
 ### 设置Runner
 Gitea Actions需要[runner](https://gitea.com/gitea/runner) 来运行Job。
 为了避免消耗过多资源并影响Gitea实例，建议您在与Gitea实例分开的机器上启动Runner。
 您可以使用[预构建的二进制文件](http://dl.gitea.com/gitea-runner)或[容器镜像](https://hub.docker.com/r/gitea/runner/tags)来设置Runner。
 在进一步操作之前，建议您先使用预构建的二进制文件以命令行方式运行它，以确保它与您的环境兼容，尤其是如果您在本地主机上运行Runner。
 如果出现问题，这样调试起来会更容易。
 该Runner可以在隔离的Docker容器中运行Job，因此您需要确保已安装Docker并且Docker守护进程正在运行。
 虽然这不是严格必需的，因为Runner也可以直接在主机上运行Job，这取决于您的配置方式。
 然而，建议使用Docker运行Job，因为它更安全且更易于管理。
 在运行Runner之前，您需要使用以下命令将其注册到Gitea实例中：
 ```bash
 gitea-runner register --no-interactive --instance <instance> --token <token>
 ```
 需要两个必需的参数：`instance` 和 `token`。
 `instance`是您的Gitea实例的地址，如`http://192.168.8.8:3000`或`https://gitea.com`。
 Runner和Job容器（由Runner启动以执行Job）将连接到此地址。
 这意味着它可能与用于Web访问的`ROOT_URL`不同。
 使用回环地址（例如 `127.0.0.1` 或 `localhost`）是一个不好的选择。
 如果不确定使用哪个地址，通常选择局域网地址即可。
 `token` 用于身份验证和标识，例如 `P2U1U0oB4XaRCi8azcngmPCLbRpUGapalhmddh23`。
 每个令牌都可用于注册多个Runner。通过重置链接替换为新令牌后，旧令牌将失效。
 您可以从以下位置获取不同级别的`token`,从而创建出相应级别的`runner`
 - 实例级别：管理员设置页面，例如 `<your_gitea.com>/-/admin/actions/runners`。
 - 组织级别：组织设置页面，例如 `<your_gitea.com>/<org>/settings/actions/runners`。
 - 存储库级别：存储库设置页面，例如 `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`。
 ![register runner](/images/usage/actions/register-runner.png)
 注册后，当前目录中将出现一个名为 `.runner` 的新文件，该文件存储了注册信息。
 请不要手动编辑该文件。
 如果该文件丢失或损坏，只需删除它然后重新注册即可。
 最后，是时候启动Runner了：
 ```bash
 gitea-runner daemon
 ```
 您可以在管理页面上看到新的Runner：
 ![view runner](/images/usage/actions/view-runner.png)
 您可以通过访问[Gitea Runner](runner) 获取更多信息。
 ### 使用Actions
 即使对于启用了Gitea实例的Actions，存储库仍默认禁用Actions。
 要启用它，请转到存储库的设置页面，例如`your_gitea.com/<owner>/repo/settings`，然后启用`Enable Repository Actions`。
 ![enable actions](/images/usage/actions/enable-actions.png)
 接下来的步骤可能相当复杂。
 您需要学习Actions的[工作流语法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)，并编写您想要的工作流文件。
 不过，我们可以从一个简单的演示开始：
 ```yaml
 name: Gitea Actions Demo
 run-name: ${{ gitea.actor }} is testing out Gitea Actions 🚀
 on: [push]
 jobs:
  Explore-Gitea-Actions:
    runs-on: ubuntu-latest
    steps:
      - run: echo "🎉 The job was automatically triggered by a ${{ gitea.event_name }} event."
      - run: echo "🐧 This job is now running on a ${{ runner.os }} server hosted by Gitea!"
      - run: echo "🔎 The name of your branch is ${{ gitea.ref }} and your repository is ${{ gitea.repository }}."
      - name: Check out repository code
        uses: actions/checkout@v4
      - run: echo "💡 The ${{ gitea.repository }} repository has been cloned to the runner."
      - run: echo "🖥️ The workflow is now ready to test your code on the runner."
      - name: List files in the repository
        run: |
          ls ${{ gitea.workspace }}
      - run: echo "🍏 This job's status is ${{ job.status }}."
 ```
 您可以将上述示例上传为一个以`.yaml`扩展名的文件，放在存储库的`.gitea/workflows/`目录中，例如`.gitea/workflows/demo.yaml`。
 您可能会注意到，这与[GitHub Actions的快速入门](https://docs.github.com/en/actions/quickstart)非常相似。
 这是因为Gitea Actions在尽可能兼容GitHub Actions的基础上进行设计。
 请注意，演示文件中包含一些表情符号。
 请确保您的数据库支持它们，特别是在使用MySQL时。
 如果字符集不是`utf8mb4`，将出现错误，例如`Error 1366 (HY000): Incorrect string value: '\\xF0\\x9F\\x8E\\x89 T...' for column 'name' at row 1`。
 有关更多信息，请参阅[数据库准备工作](../../installation/database-preparation.md#mysqlmariadb)。
 或者，您可以从演示文件中删除所有表情符号，然后再尝试一次。
 `on: [push]` 这一行表示当您向该存储库推送提交时，工作流将被触发。
 然而，当您上传 YAML 文件时，它也会推送一个提交，所以您应该在"Actions"标签中看到一个新的任务。
 ![view job](/images/usage/actions/view-job.png)
 做得好！您已成功开始使用Actions。
@@ -1,119 +0,0 @@
 ---
 date: "2026-06-26T00:00:00+00:00"
 slug: "scoped-workflows"
 sidebar_position: 60
 ---
 # 作用域工作流
 作用域工作流（Scoped Workflows）让你把 Actions 工作流集中维护在一个**源（source）**仓库中，并让它们自动在许多其他仓库上运行，而无需把工作流文件复制到每个仓库里。
 提交到源仓库作用域工作流目录下的工作流文件，会在该源所适用的每个仓库（称为**消费方（consuming）**仓库）上运行。每次运行都在**消费方仓库自身的上下文**中执行：使用它的 runner、密钥、`GITEA_TOKEN` 和分支，而工作流**内容则读取自源仓库**。这适用于在组织或实例范围内强制推行共享 CI：代码检查、安全扫描、合规或策略检查等。
 ## 级别
 源仓库可以在两个级别注册：
 - **所有者级别（Owner level）**：由组织或用户注册。该源的工作流会在该组织或用户拥有的每个仓库上运行。
 - **实例级别（Instance level）**：由站点管理员注册。该源的工作流会在实例上的**每一个**仓库上运行。
 同一个仓库可以同时在两个级别注册；对于每个匹配的事件，它仍只会被评估一次。
 :::note
 实例级别的源适用于实例上的**每一个**仓库，且被设为必需（required）的源无法被选择退出（opt out）。检测会在每个仓库的每次事件上运行。请谨慎注册。
 :::
 ## 配置
 作用域工作流存放在一个与常规工作流分开的目录中，由 `app.ini` 中 `[actions]` 段的 `SCOPED_WORKFLOW_DIRS` 控制：
 ```ini
 [actions]
 SCOPED_WORKFLOW_DIRS = .gitea/scoped_workflows
 ```
 - 默认值为 `.gitea/scoped_workflows`。
 - 可以列出多个目录（以逗号分隔）。
 - **不得与** `WORKFLOW_DIRS`（常规工作流目录，默认为 `.gitea/workflows` 和 `.github/workflows`）**重叠**。
 - 留空意味着没有任何目录存放作用域工作流，因此不会找到也不会运行任何作用域工作流。设置页面仍会显示、源仍可注册，但不会有任何作用域工作流运行。
 把作用域工作流放在它们自己的目录中，意味着源仓库**自身**的 Actions 不受影响：只有 `SCOPED_WORKFLOW_DIRS` 下的文件才会被当作作用域工作流。
 ## 从一个仓库提供作用域工作流
 1. 在准备作为源的仓库中，把工作流文件提交到其**默认分支**上的作用域工作流目录下，例如 `.gitea/scoped_workflows/lint.yaml`：
   ```yaml
   name: Lint
   on: [push, pull_request]
   jobs:
     lint:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: echo "lint the consuming repository here"
   ```
 2. 将该仓库注册为源：
   - **组织**：*组织设置 -> Actions -> 作用域工作流*
   - **用户**：*用户设置 -> Actions -> 作用域工作流*
   - **实例（管理员）**：*管理后台 -> Actions -> 作用域工作流*
   搜索并添加该仓库。此后，它的作用域工作流便会适用于该级别下的消费方仓库。
 源仓库也在它自己的作用域内，因此它会像其他消费方一样在自身上运行这些工作流。
 ## 作用域工作流如何运行
 - 该运行属于**消费方**仓库，使用它的 runner、密钥、`GITEA_TOKEN` 和 ref。它在那里的表现与普通运行一致，包括重跑、日志和提交状态。
 - 工作流**内容读取自源**仓库，并钉定在事件发生时源默认分支的 commit 上。
 - 检测使用消费方仓库的事件，因此工作流的 `on:` 触发器（例如 `push` 和 `pull_request`）必须与该事件匹配。
 ## 选择退出（Opting out）
 消费方仓库可以在其 **Actions** 页面（该工作流会显示在其源之下）禁用一个它不想要的作用域工作流。已被标记为**必需（required）**（见下文）的工作流，消费方仓库永远无法将其禁用，也无法选择退出。
 ## 必需工作流与合并门禁
 在作用域工作流设置页面上，你可以把单个工作流标记为**必需（required）**，并为每个工作流给定一个或多个**状态检查模式（status-check patterns）**（每行一个 glob）。一个必需的作用域工作流：
 - 无法被消费方仓库禁用。
 - 会对合并请求（PR）形成合并门禁：消费方的 PR 只有在一个匹配**每一个**模式的提交状态都**通过**后才能合并（必须存在且通过，must-present-and-pass）。一个从不产生任何状态的必需检查会**阻止**合并，而不是被静默跳过，因此在消费方关闭 Actions 也无法绕过它。
 作用域运行产生的状态检查 context 形如：
 ```
 <源仓库全名>: <工作流显示名> / <job> (<event>)
 ```
 设置页面会为每个工作流预览这些 “Expected status checks（预期状态检查）”，并标记出与你的模式匹配的项，便于你确认模式是否正确。一种常见模式是对 job 和 event 使用通配符，例如 `my-org/ci-repo: Lint / *`。
 强制范围：
 - 必需检查会在任何设有**分支保护规则**的目标分支上强制生效，即使该规则自身的状态检查处于关闭状态。
 - **没有**保护规则的目标分支不受门禁约束。
 :::warning
 只有运行在会产生提交状态的事件（`push`、`pull_request`、`pull_request_target`、`release`）上的工作流才能被设为必需。仅运行在 `workflow_dispatch`、`schedule` 或 `workflow_call` 等事件上的工作流不会产生任何状态，因此把它设为必需会**永久**阻止每一个消费方 PR 的合并。设置页面在这种情况下会向你发出警告。
 :::
 ## 可复用工作流（`uses:`）
 作用域工作流可以调用可复用工作流：
 - **本地**引用（`uses: ./...` 或 `uses: $/...`）会相对于**源**仓库解析：即调用方工作流内容的来源仓库，而非消费方仓库。
 - **跨仓库**引用（`uses: owner/repo/...@ref` 或 `uses: self:owner/repo/...@ref`）会以**消费方仓库的**读取权限来解析。如果它指向一个私有仓库，请确保每个消费方仓库都能读取它，否则工作流会在那里失败。
 可复用工作流可以放在源仓库的 `SCOPED_WORKFLOW_DIRS`（或 `WORKFLOW_DIRS`）之下。
 ## 安全注意事项
 源仓库的工作流内容会在它所适用的每个仓库中执行，其步骤脚本及其输出会写入该仓库的 Actions 日志，任何能查看消费方仓库 Actions 的人都能读取这些日志。
 - 因此，将一个**私有**仓库注册为源，会通过这些日志泄露其工作流逻辑。只应注册那些其工作流内容可以与每个消费方仓库共享的仓库。
 ## 限制
 - 目前不支持将 `on: schedule` 和 `on: workflow_run` 作为作用域工作流触发器。
 - 作用域工作流内容读取自源的默认分支；源的其他分支不会被使用。
@@ -1,130 +0,0 @@
 ---
 date: "2026-03-19T00:00:00+01:00"
 slug: "token-permissions"
 sidebar_position: 30
 ---
 # Actions Job令牌权限（`GITEA_TOKEN`）
 每个Actions Job都会获得一个内置令牌（`GITEA_TOKEN`），可用于访问Gitea（通过HTTP(S)访问Git、API请求等）。
 本页面介绍Gitea如何决定该令牌可以执行哪些操作。
 在工作流中，可以通过`${{ secrets.GITEA_TOKEN }}`使用该令牌。这些设置和`permissions:`仅影响`GITEA_TOKEN`（不影响个人访问令牌等其他密钥）。关于API调用，请参阅[API认证](../../development/api-usage.md#authentication)。
 <a id="where-permissions-come-from"></a>
 ## 权限来源
 Gitea按以下顺序确定Job令牌的权限：
 1. Job级别的`permissions:`（`jobs.<job_id>.permissions`）
 2. 工作流级别的`permissions:`（顶层）
 3. 设置中的默认权限（所有者或仓库）
 然后，该结果会受到所配置的最大令牌权限的**限制**（见下文）。
 <a id="supported-workflow-syntax"></a>
 ## 支持的工作流语法
 Gitea支持与GitHub Actions兼容的`permissions:`关键字。
 <a id="scalar-values"></a>
 ### 标量值
 ```yaml
 permissions: read-all   # or: write-all
 ```
 <a id="scoped-mapping"></a>
 ### 按权限范围映射
 ```yaml
 permissions:
  contents: read
  issues: write
  pull-requests: none
 ```
 每个权限范围的有效访问模式值为`read`、`write`和`none`。
 <a id="supported-scopes"></a>
 ### 支持的权限范围
 - `contents`（适用于`code`和`releases`）
 - `code`
 - `releases`
 - `issues`
 - `pull-requests`
 - `actions`
 - `wiki`
 - `projects`
 - `packages`（如果目标功能支持）
 - `id-token`（`write`允许请求[OpenID Connect令牌](openid-connect.md)，`read`不授予任何权限）
 如果同时指定了`contents`和更细粒度的权限范围（如`code`或`releases`），则该单元以更细粒度的权限范围为准。
 <a id="compatibility-notes"></a>
 ### 兼容性说明
 Gitea支持GitHub Actions权限范围的一个子集。
 Gitea Actions目前不支持`statuses`、`checks`、`deployments`、`security-events`和`pages`等GitHub专有的权限范围。
 Gitea还提供了一些仓库单元权限范围，它们在GitHub Actions中不作为独立的权限范围存在：
 - `code`
 - `releases`
 - `wiki`
 - `projects`
 <a id="default-permission-mode"></a>
 ## 默认权限模式
 如果工作流和Job都没有定义`permissions:`，Gitea会使用所配置的默认模式：
 - **宽松**：对Job所属仓库的大多数单元拥有读写权限（向后兼容的默认值）。
 - **受限**：对Job所属仓库的`code`、`releases`和`packages`拥有只读权限，默认无权访问其他单元。
 两种模式都不包含`id-token`。
 <a id="maximum-token-permissions-clamping"></a>
 ## 最大令牌权限（限制）
 您可以为每个仓库单元以及`id-token`配置最大权限。
 Job的实际权限按以下方式计算：
 `effective = min(requested, maximum)`
 这意味着工作流可以降低Job的权限，但不能超过您配置的最大权限。
 如果未配置最大权限，则所有权限范围的最大权限默认为`write`。
 在Gitea支持`id-token`之前保存的最大权限会拒绝`id-token`，直到您将其设为`write`。
 <a id="where-to-configure"></a>
 ## 配置位置
 您可以在以下位置配置默认权限和最大权限：
 - **用户/组织**：`Settings` → `Actions` → `General`
 - **仓库**：`Settings` → `Actions` → `General`
  - 对于组织中的仓库，可以遵循所有者级别的配置，也可以通过**覆盖所有者级别的配置**选择不遵循。
 注意：仅在启用**仓库Actions**后，才会显示仓库级别的令牌权限设置。
 <a id="fork-pull-requests"></a>
 ## Fork拉取请求
 出于安全考虑，由fork拉取请求触发的工作流始终只拥有仓库内容的只读权限，与工作流的`permissions:`或设置无关。这些Job也无法获取OpenID Connect令牌。
 <a id="cross-repository-access"></a>
 ## 跨仓库访问
 默认情况下，`GITEA_TOKEN`只能访问：
 - Job所属仓库（依据计算出的权限）
 - 公开仓库（只读）
 默认拒绝访问其他私有仓库。
 用户或组织可以通过**设置 → Actions → 常规 → 跨仓库访问**，允许以只读方式访问选定的私有仓库。
 私有仓库也可以通过**设置 → Actions → 常规**允许选定的协作所有者。
 这样，这些所有者的私有仓库便可读取当前私有仓库以供Actions使用，例如私有Actions和可复用工作流。
 fork拉取请求的工作流永远不会获得对私有仓库的跨仓库访问权限，即使这些仓库已被列出。
@@ -1,110 +0,0 @@
 ---
 date: "2024-04-10T22:21:00+08:00"
 slug: "actions-variables"
 sidebar_position: 25
 ---
 # 变量
 ## 环境变量
 以下环境变量会在每次工作流运行时自动设置，可以直接访问（例如在 shell 脚本中使用 `$CI`）。
 同时列出 `GITEA_*` 和 `GITHUB_*` 名称的变量值相同。
 | 名称 | 描述 | 示例 |
 |---|---|---|
 | `ACT` | 始终为 `true`，除非 Runner 配置了 `runner.set_act_env: false`。 | `true` |
 | `CI` | 始终为 `true`。 | `true` |
 | `GITEA_ACTION`<br/>`GITHUB_ACTION` | 当前步骤的 `id`，未设置时为步骤的序号。 | `0` |
 | `GITEA_ACTION_PATH`<br/>`GITHUB_ACTION_PATH` | Action 所在的路径。仅在复合 Action 中设置。 | `/var/run/act/actions/***` |
 | `GITEA_ACTION_REF`<br/>`GITHUB_ACTION_REF` | 正在执行的 Action 的 ref。 | `v4` |
 | `GITEA_ACTION_REPOSITORY`<br/>`GITHUB_ACTION_REPOSITORY` | Action 的所有者和仓库名称。 | `actions/checkout` |
 | `GITEA_ACTIONS`<br/>`GITHUB_ACTIONS` | 始终为 `true`。`GITEA_ACTIONS` 可用于区分 Gitea Actions 和其他 CI 系统。 | `true` |
 | `GITEA_ACTIONS_RUNNER_VERSION` | 执行工作流的 Runner 的版本。 | `v5.2.4` |
 | `GITEA_ACTOR`<br/>`GITHUB_ACTOR` | 触发工作流的用户的用户名。 | `alice` |
 | `GITEA_ACTOR_ID`<br/>`GITHUB_ACTOR_ID` | 触发工作流的用户的 ID。 | `1` |
 | `GITEA_API_URL`<br/>`GITHUB_API_URL` | REST API 的 URL。 | `https://gitea.example.com/api/v1` |
 | `GITEA_BASE_REF`<br/>`GITHUB_BASE_REF` | 拉取请求的目标分支。 | `main` |
 | `GITEA_DOCKER_WORKSPACE` | Docker 守护进程所见的工作区路径，用于绑定挂载到 Job 启动的容器中，例如在 compose 文件中使用 `${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data`。仅在 Job 运行于容器中时设置。 | `/var/lib/docker/volumes/GITEA-ACTIONS-TASK-42-***/_data` |
 | `GITEA_ENV`<br/>`GITHUB_ENV` | 为后续步骤设置环境变量的文件路径。 | `/var/run/act/workflow/envs.txt` |
 | `GITEA_EVENT_NAME`<br/>`GITHUB_EVENT_NAME` | 触发工作流的事件名称。 | `push` |
 | `GITEA_EVENT_PATH`<br/>`GITHUB_EVENT_PATH` | 包含事件 Webhook 负载的文件路径。 | `/var/run/act/workflow/event.json` |
 | `GITEA_GRAPHQL_URL`<br/>`GITHUB_GRAPHQL_URL` | 在 Gitea 中为空（不支持 GraphQL）。 | _（空）_ |
 | `GITEA_HEAD_REF`<br/>`GITHUB_HEAD_REF` | 拉取请求的源分支。 | `feature-branch` |
 | `GITEA_JOB`<br/>`GITHUB_JOB` | 当前 Job 的 `job_id`。 | `build` |
 | `GITEA_OUTPUT`<br/>`GITHUB_OUTPUT` | 设置步骤输出参数的文件路径。 | `/var/run/act/workflow/outputcmd.txt` |
 | `GITEA_PATH`<br/>`GITHUB_PATH` | 为后续步骤添加系统 `PATH` 条目的文件路径。 | `/var/run/act/workflow/pathcmd.txt` |
 | `GITEA_REF`<br/>`GITHUB_REF` | 触发工作流的完整 ref。 | `refs/heads/main` |
 | `GITEA_REF_NAME`<br/>`GITHUB_REF_NAME` | ref 的短名称。 | `main` |
 | `GITEA_REF_PROTECTED`<br/>`GITHUB_REF_PROTECTED` | 如果触发工作流的 ref 配置了分支保护，则为 `true`。 | `true` |
 | `GITEA_REF_TYPE`<br/>`GITHUB_REF_TYPE` | ref 的类型：`branch` 或 `tag`。 | `branch` |
 | `GITEA_REPOSITORY`<br/>`GITHUB_REPOSITORY` | 所有者和仓库名称。 | `owner/repo` |
 | `GITEA_REPOSITORY_ID`<br/>`GITHUB_REPOSITORY_ID` | 仓库的 ID。 | `123` |
 | `GITEA_REPOSITORY_OWNER`<br/>`GITHUB_REPOSITORY_OWNER` | 仓库所有者的用户名。 | `owner` |
 | `GITEA_REPOSITORY_OWNER_ID`<br/>`GITHUB_REPOSITORY_OWNER_ID` | 仓库所有者的 ID。 | `45` |
 | `GITEA_RETENTION_DAYS`<br/>`GITHUB_RETENTION_DAYS` | Artifact 的保留天数，永久保留时为空。 | `90` |
 | `GITEA_RUN_ATTEMPT`<br/>`GITHUB_RUN_ATTEMPT` | 工作流运行的尝试次数。 | `1` |
 | `GITEA_RUN_ID`<br/>`GITHUB_RUN_ID` | 每次工作流运行的唯一编号。 | `1234` |
 | `GITEA_RUN_NUMBER`<br/>`GITHUB_RUN_NUMBER` | 特定工作流每次运行的唯一编号。 | `42` |
 | `GITEA_SERVER_URL`<br/>`GITHUB_SERVER_URL` | Gitea 实例的 URL。 | `https://gitea.example.com` |
 | `GITEA_SHA`<br/>`GITHUB_SHA` | 触发工作流的提交 SHA。 | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
 | `GITEA_STATE`<br/>`GITHUB_STATE` | 设置步骤状态变量的文件路径。 | `/var/run/act/workflow/statecmd.txt` |
 | `GITEA_STEP_SUMMARY`<br/>`GITHUB_STEP_SUMMARY` | 写入 Job 摘要的文件路径。 | `/var/run/act/workflow/step-summary-0.md` |
 | `GITEA_TRIGGERING_ACTOR`<br/>`GITHUB_TRIGGERING_ACTOR` | 发起工作流运行的用户的用户名。重新运行时可能与 `GITEA_ACTOR` 不同。 | `alice` |
 | `GITEA_WORKFLOW`<br/>`GITHUB_WORKFLOW` | 工作流的名称。 | `CI` |
 | `GITEA_WORKFLOW_SHA`<br/>`GITHUB_WORKFLOW_SHA` | 工作流文件的提交 SHA。 | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
 | `GITEA_WORKSPACE`<br/>`GITHUB_WORKSPACE` | Runner 上的默认工作目录。 | `/workspace/owner/repo` |
 | `TRACEPARENT` | Job span 的 W3C 追踪上下文，供已接入追踪的工具将 span 添加到 Job 的追踪中。仅在 Runner 导出追踪数据时设置，参见[监控](/runner/monitoring/#opentelemetry)。 | `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01` |
 | `TRACESTATE` | 随 `TRACEPARENT` 附带的厂商特定追踪数据。仅在追踪包含此类数据时设置。 | `rojo=00f067aa0ba902b7` |
 ### Runner 环境变量
 | 名称 | 描述 | 示例 |
 |---|---|---|
 | `ImageOS` | Job 镜像的操作系统和版本，供 `setup-*` Action 读取。 | `ubuntu24` |
 | `RUNNER_ARCH` | Runner 的架构。 | `X64` |
 | `RUNNER_DEBUG` | 当 `ACTIONS_STEP_DEBUG` 密钥为 `true` 时设置为 `1`，否则不设置。 | `1` |
 | `RUNNER_ENVIRONMENT` | 始终为 `self-hosted`。 | `self-hosted` |
 | `RUNNER_NAME` | 执行 Job 的 Runner 的名称。 | `my-runner` |
 | `RUNNER_OS` | Runner 的操作系统。 | `Linux` |
 | `RUNNER_TEMP` | Runner 上临时目录的路径。 | `/tmp` |
 | `RUNNER_TOOL_CACHE` | Runner 上工具缓存目录的路径。 | `/opt/hostedtoolcache` |
 | `RUNNER_WORKSPACE` | `GITEA_WORKSPACE` 的父目录。 | `/workspace/owner` |
 ### 内部环境变量
 这些变量供 Runner 和 Action 内部使用，工作流中通常不需要直接使用。
 | 名称 | 描述 | 示例 |
 |---|---|---|
 | `ACTIONS_CACHE_URL` | Actions 缓存服务的 URL。 | `http://192.168.1.10:8088/` |
 | `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | 用于 OIDC 请求的令牌。仅在授予 `id-token: write` 时设置。 | `***` |
 | `ACTIONS_ID_TOKEN_REQUEST_URL` | 请求 OIDC 令牌的 URL。仅在授予 `id-token: write` 时设置。 | `https://gitea.example.com/api/actions/oidc/token?` |
 | `ACTIONS_RESULTS_URL` | 存储 Artifact 的 URL。 | `https://gitea.example.com` |
 | `ACTIONS_RUNTIME_TOKEN` | Actions 流水线 API 的认证令牌。 | `***` |
 | `ACTIONS_RUNTIME_URL` | Gitea Actions 流水线 API 的 URL。 | `https://gitea.example.com/api/actions_pipeline/` |
 ## 用户定义的变量
 您可以创建用户、组织和仓库级别的变量。变量的级别取决于创建它的位置。当创建变量时，变量的名称会被
 转换为大写，在yaml文件中引用时需要使用大写。
 ### 命名规则
 以下规则适用于变量名：
 - 变量名称只能包含字母数字字符 (`[a-z]`, `[A-Z]`, `[0-9]`) 或下划线 (`_`)。不允许使用空格。
 - 变量名称不能以 `GITHUB_` 和 `GITEA_` 前缀开头。
 - 变量名称不能以数字开头。
 - 变量名称不区分大小写。
 - 变量名称在创建它们的级别上必须是唯一的。
 - 变量名称不能为 `CI`。
 ### 使用
 创建配置变量后，它们将自动填充到 `vars` 上下文中。您可以在工作流中使用类似 `${{ vars.VARIABLE_NAME }}` 这样的表达式来使用它们。
 ### 优先级
 如果同名变量存在于多个级别，则级别最低的变量优先。
 仓库级别的变量总是比组织或者用户级别的变量优先被选中。
@@ -1,9 +0,0 @@
 {
  "label": "项目",
  "position": 60,
  "link": {
    "type": "generated-index",
    "slug": "/usage/projects",
    "description": "使用项目看板规划和跟踪工作"
  }
 }
@@ -1,82 +0,0 @@
 ---
 date: "2025-11-25T18:58:22Z"
 slug: "project-workflows"
 sidebar_position: 1
 description: "通过事件驱动的过滤器和动作自动化项目看板。"
 ---
 # 项目工作流
 项目工作流可自动化项目看板。当项目中的问题或合并请求触发事件时，该事件下每个已启用的工作流都会检查其过滤条件并执行相应动作。工作流在 Gitea 中运行，无需运行器。
 ## 编辑工作流
 1. 打开项目并选择 **Workflows**。
 2. 在侧边栏中选择事件。
 3. 设置过滤器和动作，然后选择 **Save**。要修改现有工作流，请先选择 **Edit**。
 一个事件可以有多个工作流。**Clone** 会复制选中的工作流，便于调整后用于其他条目。**Disable** 会暂停工作流并保留其配置。**Remove** 会删除工作流。
 ## 事件
 | 事件 | 触发时机 | 过滤器 | 动作 |
 | --- | --- | --- | --- |
 | Item added to project | 条目被添加到项目或在项目中创建时 | Apply to、标签 | Move to column、标签、问题状态 |
 | Item removed from project | 条目被移出项目时 | Apply to、标签 | 标签、问题状态 |
 | Item reopened | 条目被重新打开时 | Apply to、标签 | Move to column、标签 |
 | Item closed | 条目被关闭时 | Apply to、标签 | Move to column、标签 |
 | Item column changed | 条目移至另一列时 | Apply to、列、标签 | 标签、问题状态 |
 | Code changes requested | 正式审查者要求修改合并请求时 | 标签 | Move to column、标签 |
 | Code review approved | 正式审查者批准合并请求时 | 标签 | Move to column、标签 |
 | Pull request merged | 合并请求被合并时 | 标签 | Move to column、标签 |
 ## 过滤器
 未设置过滤器的工作流会对每个条目运行。
 - **Apply to**：问题、合并请求或两者。
 - **When moved from column**、**When moved to column**：条目离开或进入的列。
 - **Only if it has labels**：条目必须包含所有选中的标签。
 ## 动作
 工作流至少需要一个动作。动作按以下顺序执行：
 1. **Move to column**：将条目移至某一列。
 2. **Add labels**、**Remove labels**：更改条目的标签。
 3. **Issue state**：关闭或重新打开条目。工作流不会重新打开合并请求。
 工作流所做的更改在时间线中显示为“Project workflow”及其后的事件名称，且不会触发其他工作流。工作流不会在已关闭的项目中运行，也不会处理已归档仓库中的条目。
 ## 权限
 任何拥有项目读取权限的人都可以查看其工作流。管理工作流需要项目的写入权限，并满足以下条件：
 - 仓库项目：拥有该仓库的问题和合并请求的写入权限。
 - 组织项目：是组织所有者或站点管理员。
 - 用户项目：是项目所有者。
 仅限公开仓库的访问令牌无法管理组织或用户项目的工作流。无论谁触发事件，工作流都会执行其动作。
 ## API
 可通过仓库（`/repos/{owner}/{repo}/projects/{id}`）、组织（`/orgs/{org}/projects/{id}`）或已认证用户（`/user/projects/{id}`）的项目路由管理工作流：
 | 方法 | 路径 | 用途 |
 | --- | --- | --- |
 | `GET` | `.../workflows` | 列出工作流 |
 | `GET` | `.../workflows/{workflow_id}` | 获取工作流 |
 | `POST` | `.../workflows` | 创建工作流 |
 | `PATCH` | `.../workflows/{workflow_id}` | 编辑工作流，未提供的字段保持不变 |
 | `DELETE` | `.../workflows/{workflow_id}` | 删除工作流 |
 工作流包含 `event`（`item_added_to_project`、`item_removed_from_project`、`item_reopened`、`item_closed`、`item_column_changed`、`code_changes_requested`、`code_review_approved` 或 `pull_request_merged`）、`enabled` 标志、`filters`（`issue_type`、`source_column_id`、`target_column_id`、`label_ids`）以及 `actions`（`column_id`、`add_label_ids`、`remove_label_ids`、`issue_state`）。每个事件仅接受[事件](#事件)表中列出的过滤器和动作。
 ## 示例
 要将新的缺陷报告分流至待分类列，请为 **Item added to project** 创建工作流：
 - **Apply to**：Issues only
 - **Only if it has labels**：`bug`
 - **Move to column**：Triage
 - **Add labels**：`needs-triage`
@@ -1,373 +0,0 @@
 ---
 date: "2016-12-01T16:00:00+02:00"
 slug: "install-with-docker"
 sidebar_position: 70
 aliases:
  - /zh-cn/install-with-docker
 ---
 # 使用 Docker 安装
 Gitea 在其 Docker Hub 组织内提供自动更新的 Docker 镜像。可以始终使用最新的稳定标签或使用其他服务来更新 Docker 镜像。
 该参考设置指导用户完成基于 `docker-compose` 的设置，但是 `docker-compose` 的安装不在本文档的范围之内。要安装 `docker-compose` 本身，请遵循官方[安装说明](https://docs.docker.com/compose/install/)。
 ## 基本
 最简单的设置只是创建一个卷和一个网络，然后将 `docker.gitea.com/gitea:latest` 镜像作为服务启动。由于没有可用的数据库，因此可以使用 SQLite3 初始化数据库。创建一个类似 `gitea` 的目录，并将以下内容粘贴到名为 `docker-compose.yml` 的文件中。请注意，该卷应由配置文件中指定的 UID/GID 的用户/组拥有。如果您不授予卷正确的权限，则容器可能无法启动。另请注意，标签 `:latest` 安装的是最新的稳定版本。对于稳定的发行版，您也可以使用 `:1` 或指定某个发行版，例如 `@dockerVersion@`。如果您想使用最新的开发版本，则可以使用 `:main-nightly` 标签；如果您想运行发布分支的最新提交，可以使用 `:1.x-nightly` 标签，其中 x 是 Gitea 的次要版本号（例如:`1.27-nightly`）。
 ```yaml
 version: "3"
 networks:
  gitea:
    external: false
 services:
  server:
    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
    restart: always
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
 ```
 ## 端口
 要将集成的 openSSH 守护进程和 Web 服务器绑定到其他端口，请调整端口部分。通常，只需更改主机端口，容器内的端口保持原样即可。
 ```diff
 version: "3"
 networks:
  gitea:
    external: false
 services:
  server:
    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
    restart: always
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
 -     - "3000:3000"
 -     - "222:22"
 +     - "8080:3000"
 +     - "2221:22"
 ```
 ## 数据库
 ### MySQL 数据库
 要将 Gitea 与 MySQL 数据库结合使用，请将这些更改应用于上面创建的 `docker-compose.yml` 文件。
 ```diff
 version: "3"
 networks:
  gitea:
    external: false
 services:
  server:
    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
 +      - GITEA__database__DB_TYPE=mysql
 +      - GITEA__database__HOST=db:3306
 +      - GITEA__database__NAME=gitea
 +      - GITEA__database__USER=gitea
 +      - GITEA__database__PASSWD=gitea
    restart: always
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
 +    depends_on:
 +      - db
 +
 +  db:
 +    image: docker.io/library/mysql:8
 +    restart: always
 +    environment:
 +      - MYSQL_ROOT_PASSWORD=gitea
 +      - MYSQL_USER=gitea
 +      - MYSQL_PASSWORD=gitea
 +      - MYSQL_DATABASE=gitea
 +    networks:
 +      - gitea
 +    volumes:
 +      - ./mysql:/var/lib/mysql
 ```
 ### PostgreSQL 数据库
 要将 Gitea 与 PostgreSQL 数据库结合使用，请将这些更改应用于上面创建的 `docker-compose.yml` 文件。
 ```diff
 version: "3"
 networks:
  gitea:
    external: false
 services:
  server:
    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
 +      - GITEA__database__DB_TYPE=postgres
 +      - GITEA__database__HOST=db:5432
 +      - GITEA__database__NAME=gitea
 +      - GITEA__database__USER=gitea
 +      - GITEA__database__PASSWD=gitea
    restart: always
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
 +    depends_on:
 +      - db
 +
 +  db:
 +    image: docker.io/library/postgres:14
 +    restart: always
 +    environment:
 +      - POSTGRES_USER=gitea
 +      - POSTGRES_PASSWORD=gitea
 +      - POSTGRES_DB=gitea
 +    networks:
 +      - gitea
 +    volumes:
 +      - ./postgres:/var/lib/postgresql/data
 ```
 ## 命名卷
 要使用命名卷而不是主机卷，请在 `docker-compose.yml` 配置中定义并使用命名卷。此更改将自动创建所需的卷。您无需担心命名卷的权限；Docker 将自动处理该问题。
 ```diff
 version: "3"
 networks:
  gitea:
    external: false
 +volumes:
 +  gitea:
 +    driver: local
 +
 services:
  server:
    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    restart: always
    networks:
      - gitea
    volumes:
 -      - ./gitea:/data
 +      - gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
 ```
 MySQL 或 PostgreSQL 容器将需要分别创建。
 ## 启动
 要基于 `docker-compose` 启动此设置，请执行 `docker-compose up -d`，以在后台启动 Gitea。使用 `docker-compose ps` 将显示 Gitea 是否正确启动。可以使用 `docker-compose logs` 查看日志。
 要关闭设置，请执行 `docker-compose down`。这将停止并杀死容器。这些卷将仍然存在。
 注意：如果在 http 上使用非 3000 端口，请更改 app.ini 以匹配 `LOCAL_ROOT_URL = http://localhost:3000/`。
 ## 安装
 通过 `docker-compose` 启动 Docker 安装后，应该可以使用喜欢的浏览器访问 Gitea，以完成安装。访问 http://server-ip:3000 并遵循安装向导。如果数据库是通过上述 `docker-compose` 设置启动的，请注意，必须将 `db` 用作数据库主机名。
 ## 环境变量
 您可以通过环境变量配置 Gitea 的一些设置：
 （默认值以**粗体**显示）
 - `APP_NAME`：**“Gitea: Git with a cup of tea”**：应用程序名称，在页面标题中使用。
 - `RUN_MODE`：**prod**：应用程序运行模式，会影响性能和调试。"dev"，"prod"或"test"。
 - `DOMAIN`：**localhost**：此服务器的域名，用于 Gitea UI 中显示的 http 克隆 URL。
 - `SSH_DOMAIN`：**localhost**：该服务器的域名，用于 Gitea UI 中显示的 ssh 克隆 URL。如果启用了安装页面，则 SSH 域服务器将采用以下形式的 DOMAIN 值（保存时将覆盖此设置）。
 - `SSH_PORT`：**22**：克隆 URL 中显示的 SSH 端口。
 - `SSH_LISTEN_PORT`：**%(SSH_PORT)s**：内置 SSH 服务器的端口。
 - `DISABLE_SSH`：**false**：如果不可用，请禁用 SSH 功能。如果要禁用 SSH 功能，则在安装 Gitea 时应将 SSH 端口设置为 `0`。
 - `HTTP_PORT`：**3000**：HTTP 监听端口。
 - `ROOT_URL`：**""**：覆盖自动生成的公共 URL。如果内部 URL 和外部 URL 不匹配（例如在 Docker 中），这很有用。
 - `LFS_START_SERVER`：**false**：启用 git-lfs 支持。
 - `DB_TYPE`：**sqlite3**：正在使用的数据库类型[mysql，postgres，mssql，sqlite3]。
 - `DB_HOST`：**localhost:3306**：数据库主机地址和端口。
 - `DB_NAME`：**gitea**：数据库名称。
 - `DB_USER`：**root**：数据库用户名。
 - `DB_PASSWD`：**"_empty_"** ：数据库用户密码。如果您在密码中使用特殊字符，请使用“您的密码”进行引用。
 - `INSTALL_LOCK`：**false**：禁止访问安装页面。
 - `SECRET_KEY`：**""** ：全局密钥。这应该更改。如果它具有一个值并且 `INSTALL_LOCK` 为空，则 `INSTALL_LOCK` 将自动设置为 `true`。
 - `DISABLE_REGISTRATION`：**false**：禁用注册，之后只有管理员才能为用户创建帐户。
 - `REQUIRE_SIGNIN_VIEW`：**false**：启用此选项可强制用户登录以查看任何页面。
 - `USER_UID`：**1000**：在容器内运行 Gitea 的用户的 UID（Unix 用户 ID）。如果使用主机卷，则将其与 `/data` 卷的所有者的 UID 匹配（对于命名卷，则不需要这样做）。
 - `USER_GID`：**1000**：在容器内运行 Gitea 的用户的 GID（Unix 组 ID）。如果使用主机卷，则将其与 `/data` 卷的所有者的 GID 匹配（对于命名卷，则不需要这样做）。
 ## 自定义
 [此处](../administration/customizing-gitea.md)描述的定制文件应放在 `/data/gitea` 目录中。如果使用主机卷，则访问这些文件非常容易；对于命名卷，可以通过另一个容器或通过直接访问 `/var/lib/docker/volumes/gitea_gitea/_data` 来完成。安装后，配置文件将保存在 `/data/gitea/conf/app.ini` 中。
 ## 升级
 :::warning
 :exclamation::exclamation: **确保已将数据卷到 Docker 容器外部的某个位置** :exclamation::exclamation:
 :::
 要将安装升级到最新版本：
 ```bash
 # Edit `docker-compose.yml` to update the version, if you have one specified
 # Pull new images
 docker-compose pull
 # Start a new container, automatically removes old one
 docker-compose up -d
 ```
 ## 使用环境变量管理部署
 除了上面的环境变量之外，`app.ini` 中的任何设置都可以使用以下形式的环境变量进行设置或覆盖：`GITEA__SECTION_NAME__KEY_NAME`。 每次 docker 容器启动时都会应用这些设置。 完整信息在[这里](https://github.com/go-gitea/gitea/tree/master/contrib/environment-to-ini)。
 ```bash
 ...
 services:
  server:
    environment:
      - GITEA__mailer__ENABLED=true
      - GITEA__mailer__FROM=${GITEA__mailer__FROM:?GITEA__mailer__FROM not set}
      - GITEA__mailer__PROTOCOL=smtps
      - GITEA__mailer__HOST=${GITEA__mailer__HOST:?GITEA__mailer__HOST not set}
      - GITEA__mailer__USER=${GITEA__mailer__USER:-apikey}
      - GITEA__mailer__PASSWD="""${GITEA__mailer__PASSWD:?GITEA__mailer__PASSWD not set}"""
 ```
 Gitea 将为每次新安装自动生成新的 `SECRET_KEY` 并将它们写入 `app.ini`。 如果您想手动设置 `SECRET_KEY`，您可以使用以下 docker 命令来使用 Gitea 内置的[方法](../administration/command-line.md#generate)生成 `SECRET_KEY`。 安装后请妥善保管您的 `SECRET_KEY`，如若丢失则无法解密已加密的数据。
 以下命令将向 `stdout` 输出一个新的 `SECRET_KEY` 和 `INTERNAL_TOKEN`，然后您可以将其放入环境变量中。
 ```bash
 docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret SECRET_KEY
 docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret INTERNAL_TOKEN
 ```
 ```yaml
 ---
 services:
  server:
    environment:
      - GITEA__security__SECRET_KEY=[value returned by generate secret SECRET_KEY]
      - GITEA__security__INTERNAL_TOKEN=[value returned by generate secret INTERNAL_TOKEN]
 ```
 ## SSH 容器直通
 由于 SSH 在容器内运行，因此，如果需要 SSH 支持，则需要将 SSH 从主机传递到容器。一种选择是在非标准端口上运行容器 SSH（或将主机端口移至非标准端口）。另一个可能更直接的选择是将 SSH 连接从主机转发到容器。下面将说明此设置。
 本指南假定您已经在名为 `git` 的主机上创建了一个用户，该用户与容器值 `USER_UID`/`USER_GID` 共享相同的 `UID`/`GID`。这些值可以在 `docker-compose.yml` 中设置为环境变量：
 ```bash
 environment:
  - USER_UID=1000
  - USER_GID=1000
 ```
 接下来将主机的 `/home/git/.ssh` 装入容器。否则，SSH 身份验证将无法在容器内运行。
 ```bash
 volumes:
  - /home/git/.ssh/:/data/git/.ssh
 ```
 现在，需要在主机上创建 SSH 密钥对。该密钥对将用于向主机验证主机上的 `git` 用户。
 ```bash
 sudo -u git ssh-keygen -t rsa -b 4096 -C "Gitea Host Key"
 ```
 在下一步中，需要在主机上创建一个名为 `/usr/local/bin/gitea` 的文件（具有可执行权限）。该文件将发出从主机到容器的 SSH 转发。将以下内容添加到 `/usr/local/bin/gitea`：
 ```bash
 ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $0 $@"
 ```
 为了使转发正常工作，需要将容器（22）的 SSH 端口映射到 `docker-compose.yml` 中的主机端口 2222。由于此端口不需要暴露给外界，因此可以将其映射到主机的 `localhost`：
 ```bash
 ports:
  # [...]
  - "127.0.0.1:2222:22"
 ```
 另外，主机上的 `/home/git/.ssh/authorized_keys` 需要修改。它需要以与 Gitea 容器内的 `authorized_keys` 相同的方式进行操作。因此，将您在上面创建的密钥（“Gitea 主机密钥”）的公共密钥添加到 `/home/git/.ssh/authorized_keys`。这可以通过 `echo "$(cat /home/git/.ssh/id_rsa.pub)" >> /home/git/.ssh/authorized_keys` 完成。重要提示：来自 `git` 用户的公钥需要“按原样”添加，而通过 Gitea 网络界面添加的所有其他公钥将以 `command="/app [...]` 作为前缀。
 该文件应该看起来像：
 ```bash
 # SSH pubkey from git user
 ssh-rsa <Gitea Host Key>
 # other keys from users
 command="/usr/local/bin/gitea --config=/data/gitea/conf/app.ini serv key-1",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty <user pubkey>
 ```
 这是详细的说明，当发出 SSH 请求时会发生什么：
 1. 使用 `git` 用户向主机发出 SSH 请求，例如 `git clone git@domain:user/repo.git`。
 2. 在 `/home/git/.ssh/authorized_keys` 中，该命令执行 `/usr/local/bin/gitea` 脚本。
 3. `/usr/local/bin/gitea` 将 SSH 请求转发到端口 2222，该端口已映射到容器的 SSH 端口（22）。
 4. 由于 `/home/git/.ssh/authorized_keys` 中存在 `git` 用户的公钥，因此身份验证主机 → 容器成功，并且 SSH 请求转发到在 docker 容器中运行的 Gitea。
 如果在 Gitea Web 界面中添加了新的 SSH 密钥，它将以与现有密钥相同的方式附加到 `.ssh/authorized_keys` 中。
 **注意**
 SSH 容器直通仅在以下情况下有效
 - 在容器中使用 `opensshd`
 - 如果未将 `AuthorizedKeysCommand` 与 `SSH_CREATE_AUTHORIZED_KEYS_FILE = false` 结合使用以禁用授权文件密钥生成
 - `LOCAL_ROOT_URL` 不变
@@ -1,29 +0,0 @@
 {
  "sidebar.docs.category.Installation": {
    "message": "安装"
  },
  "sidebar.docs.category.Administration": {
    "message": "管理"
  },
  "sidebar.docs.category.Usage": {
    "message": "使用"
  },
  "sidebar.docs.category.actions": {
    "message": "Actions"
  },
  "sidebar.docs.category.packages": {
    "message": "软件包"
  },
  "sidebar.docs.category.Development": {
    "message": "开发"
  },
  "sidebar.docs.category.Contributing": {
    "message": "贡献"
  },
  "sidebar.docs.category.Help": {
    "message": "帮助"
  },
  "sidebar.docs.doc.What is Gitea?": {
    "message": "Gitea是什么?"
  }
 }
@@ -1,9 +0,0 @@
 {
  "label": "运维",
  "position": 30,
  "link": {
    "type": "generated-index",
    "slug": "/administration",
    "title": "运维"
  }
 }
@@ -1,34 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 slug: adding-legal-pages
 sidebar_position: 110
 aliases:
  - /zh-cn/adding-legal-pages
 ---
 # 添加法律页面
 一些法域（例如欧盟）要求在网站上添加特定的法律页面（例如隐私政策）。按照以下步骤将它们添加到你的 Gitea 实例中。
 ## 获取页面
 Gitea 源代码附带了示例页面，位于 `contrib/service/sample-page` 目录中。将它们复制到 `custom/public/assets/` 目录下。例如，如果要添加隐私政策：
 ```
 wget -O /path/to/custom/public/assets/privacy.html https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/service/sample-page/privacy.html.sample
 ```
 现在，你需要编辑该页面以满足你的需求。特别是，你必须更改电子邮件地址、网址以及与 "Your Gitea Instance" 相关的引用，以匹配你的情况。
 请务必不要放置会暗示 Gitea 项目对你的服务器负责的一般服务条款或隐私声明。
 ## 使其可见
 创建或追加到 `/path/to/custom/templates/custom/extra_links_footer.tmpl` 文件中：
 ```go
 <a class="item" href="{{AppSubUrl}}/assets/privacy.html">隐私政策</a>
 ```
 重启 Gitea 以查看更改。
@@ -1,301 +0,0 @@
 ---
 date: "2016-12-01T16:00:00+02:00"
 slug: "authentication"
 sidebar_position: 10
 aliases:
  - /zh-cn/authentication
 ---
 # 认证
 ## 轻量级目录访问协议（Lightweight Directory Access Protocol，LDAP）
 通过 BindDN 的 LDAP 和简单认证方式 LDAP 共享以下字段:
 - 认证名称 **(必选)**
  - 分配给新授权方法的名称。
 - 主机名 **(必选)**
  - LDAP 服务的主机地址.
  - 例如:`mydomain.com`
 - 端口号 **(必选)**
  - LDAP 服务的端口号.
  - 例如: LDAP `389`/ LDAPs `636`
 - 安全协议 (可选)
  - 连接 LDAP 服务器时是否使用 TLS 协议。
 - 管理员过滤规则 (可选)
  - 一个 LDAP 过滤器，用于指定哪些用户应该被赋予管理员特权。如果用户帐户符合过滤器条件，则该用户将被授予管理员权限。
  - 示例:`(objectClass=adminAccount)`
  - 适用于 Microsoft Active Directory（AD）的示例:`memberOf=CN=admin-group,OU=example,DC=example,DC=org`
 - 用户名属性（可选）
  - 用户 LDAP 记录中包含用户名称的属性。在第一次成功登录后，将使用指定的属性值作为新的 Gitea 账户用户名。若留空，则使用登录表单上提供的用户名。
  - 当提供的登录名与多个属性匹配时，这一选项非常有用，但是只有一个特定属性应该用于 Gitea 账户名称，请参阅"用户过滤器"。
  - 示例:uid
  - 适用于 Microsoft Active Directory（AD）的示例:`sAMAccountName`
 - 名字属性（可选）
  - 用户 LDAP 记录中包含用户名字的属性。将用于填充他们的账户信息。
  - 示例:givenName
 - 姓氏属性（可选）
  - 用户 LDAP 记录中包含用户姓氏的属性。将用于填充他们的账户信息。
  - 示例:`sn`
 - 电子邮件属性 **(必选)**
  - 用户 LDAP 记录中包含用户电子邮件地址的属性。将用于填充他们的账户信息。
  - 示例:`mail`
 ### LDAP(via BindDN)
 需要额外设置以下字段:
 - 绑定 DN (可选)
  - 搜索用户时绑定到 LDAP 服务器的 DN。这可以留空以执行匿名搜索。
  - 示例: `cn=Search,dc=mydomain,dc=com`
 - 绑定密码 (可选)
  - 上述指定的 Bind DN（绑定区别名）的密码，如果有的话。注意：该密码在服务器上使用 SECRET_KEY 进行加密存储。仍然建议确保 Bind DN 具有尽可能少的权限。
 - 用户搜索基准 **(必选)**
  - 这是用于搜索用户帐户的 LDAP 基础路径.
  - 示例: `ou=Users,dc=mydomain,dc=com`
 - 用户过滤规则 **(必选)**
  - LDAP 过滤器声明如何查找试图进行身份验证的用户记录
    `%[1]s`匹配参数将替换为登录表单中给出的登录名
  - 示例: `(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))`
  - 示例 for Microsoft Active Directory (AD): `(&(objectCategory=Person)(memberOf=CN=user-group,OU=example,DC=example,DC=org)(sAMAccountName=%s)(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))`
  - 如需多次替换，应使用 `%[1]s`，例如在将提供的登录名与多个属性（如用户标识符、电子邮件甚至电话号码）进行匹配时。
  - 示例: `(&(objectClass=Person)(|(uid=%[1]s)(mail=%[1]s)(mobile=%[1]s)))`
 - 启用用户同步
  - 这个选项启用了一个周期性任务，用于将 Gitea 用户与 LDAP 服务器进行同步。默认的同步周期是每 24 小时，
    但您可以在 app.ini 文件中进行更改。
    有关此部分的详细说明，请参阅[sample
    app.ini](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini)
    的*cron.sync_external_users* 部分的注释。前面提到的*User Search Base*和*User Filter*
    设置将限制哪些用户可以使用 Gitea 以及哪些用户将被同步。
    在初始运行任务时，将根据给定的设置创建所有与 LDAP 匹配的用户，因此在使用大型企业 LDAP 目录时需要小心。
 ### LDAP(simple auth)
 需要额外设置以下字段:
 - 用户 DN **(必选)**
  - 用作用户 DN 的模板。匹配参数 `%s` 将替换为登录表单中的登录名。
  - 示例: `cn=%s,ou=Users,dc=mydomain,dc=com`
  - 示例: `uid=%s,ou=Users,dc=mydomain,dc=com`
 - 用户搜索基准 (可选)
  - 用户搜索基准声明哪些用户帐户将被搜索.
  - 示例: `ou=Users,dc=mydomain,dc=com`
 - 用户过滤规则 **(必选)**
  - LDAP 过滤器声明何时允许用户登录
    `%[1]s`匹配参数将替换为登录表单中给出的登录名。
  - 示例: `(&(objectClass=posixAccount)(|(cn=%[1]s)(mail=%[1]s)))`
  - 示例: `(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))`
 ### 使用 LDAP 验证分组成员
 使用以下字段:
 - 群组搜索基础 DN(可选)
  - 组使用的 LDAP DN。
  - 示例: `ou=group,dc=mydomain,dc=com`
 - 组名过滤器 (可选)
  - LDAP 过滤器，声明如何在上述 DN 中查找有效组。
  - 示例: `(|(cn=gitea_users)(cn=admins))`
 - 组中的用户属性 (可选)
  - 组中列出了哪个用户的 LDAP 属性。
  - 示例: `uid`
 - 用户组属性 (可选)
  - 哪个组的 LDAP 属性包含一个高于用户属性名称的数组。
  - 示例: `memberUid`
 ## 可插拔式认证模块(Pluggable Authentication Module,PAM)
 这个过程启用了 PAM（Pluggable Authentication Modules）认证。用户仍然可以通过用户管理手动添加到系统中。
 PAM 提供了一种机制，通过对用户进行 PAM 认证来自动将其添加到当前数据库中。为了与普通的 Linux 密码一起使用，
 运行 Gitea 的用户还必须具有对`/etc/shadow`的读取权限，以便在使用公钥登录时检查账户的有效性。
 **注意**:如果用户已将 SSH 公钥添加到 Gitea 中，使用这些密钥可能会绕过登录检查系统。因此，
 如果您希望禁用使用 PAM 进行身份验证的用户，应该在 Gitea 中手动禁用该账户，使用内置的用户管理功能。
 1. 配置和安装准备.
   - 建议您创建一个管理用户.
   - 建议取消自动注册.
 1. 一旦数据库已初始化完成，使用新创建的管理员账户登录.
 1. 导航至用户设置（右上角的图标），然后选择
   `Site Administration` -> `Authentication Sources`, 并选择
   `Add Authentication Source`.
 1. 填写字段如下:
   - 认证类型:`PAM`。
   - 名称:任何有效的值都可以，如果您愿意，可以使用"System Authentication"。
   - PAM 服务名称:从/etc/pam.d/目录下选择适用于所需认证的正确文件[^1]。
   - PAM 电子邮件域:用户认证时要附加的电子邮件后缀。例如，如果登录系统期望一个名为 gituse 的用户，
     并且将此字段设置为 mail.com，那么 Gitea 在验证一个 GIT 实例的用户时将期望 user emai 字段为gituser@mail.com[^2]。
 **Note**: PAM 支持通过[build-time flags](installation/from-source.md#build)添加,
 而官方提供的二进制文件通常不会默认启用此功能。PAM 需要确保系统上有必要的 libpam 动态库，并且编译器可以访问必要的 PAM 开发头文件。
 [^1]:
    例如，在 Debian "Bullseye"上使用标准 Linux 登录，可以使用`common-session-noninteractive`。这个值对于其他版本的 Debian，
    包括 Ubuntu 和 Mint，可能也是有效的，请查阅您所使用发行版的文档以确认。
 [^2]: **PAM 的必选项** 请注意:在上面的示例中，用户将作为`gituser`而不是`[email protected]`登录到 Gitea 的 Web 界面。
 ## 简单邮件传输协议(Simple Mail Transfer Protocol,SMTP)
 此选项允许 Gitea 以 Gitea 用户身份登录 SMTP 主机。请设置以下字段:
 - 身份验证名称 **(必选)**
  - 分配给新授权方法的名称
 - SMTP 验证类型 **(必选)**
  - 用于连接 SMTP 主机的验证类型，plain 或 login
 - 主机名 **(必选)**
  - SMTP 服务的主机地址
  - 例如:`smtp.mydomain.com`
 - 端口号 **(必选)**
  - SMTP 服务的端口号
  - 例如: `587`
 - 允许的域名
  - 如果使用公共 SMTP 主机或有多个域的 SMTP 主机，限制哪些域可以登录
    限制哪些域可以登录。
  - 示例: `gitea.com,mydomain.com,mydomain2.com`
 - 强制使用 SMTPS
  - 默认情况下将使用 SMTPS 连接到端口 465.如果您希望将 smtp 用于其他端口，自行设置
  - 否则，如果服务器提供' STARTTLS '扩展名，则将使用此扩展名
 - 跳过 TLS 验证
  - 禁用 TLS 验证身份.
 - 该认证源处于激活状态
  - 启用或禁用此身份验证源
 ## FreeIPA
 - 要使用 FreeIPA 凭据登录 Gitea，需要为 Gitea 创建一个绑定帐户。
  创建一个绑定帐户:
 - 在 FreeIPA 服务器上创建一个 gitea.ldif 文件，并将`dc=example,dc=com`替换为您的`dn`，然后提供一个适当安全的密码。
  ```sh
  dn: uid=gitea,cn=sysaccounts,cn=etc,dc=example,dc=com
  changetype: add
  objectclass: account
  objectclass: simplesecurityobject
  uid: gitea
  userPassword: secure password
  passwordExpirationTime: 20380119031407Z
  nsIdleTimeout: 0
  ```
 - 导入 LDIF 文件（如果需要，请将 localhost 更改为 IPA 服务器）。系统会提示您输入 Directory Manager 的密码。:
  ```sh
  ldapmodify -h localhost -p 389 -x -D \
  "cn=Directory Manager" -W -f gitea.ldif
  ```
 - 为`gitea_users`添加 IPA 组:
  ```sh
  ipa group-add --desc="Gitea Users" gitea_users
  ```
 - **提示**:对于 IPA 凭证错误，运行' kinit admin '并提供域管理帐户密码.
 - 以管理员身份登录 Gitea，点击 Admin Panel 下的`Authentication`。然后单击`Add New Source`并填写详细信息，更改所有适当的地方。
 ## SPNEGO with SSPI (Kerberos/NTLM, for Windows only)
 Gitea 支持通过 Windows 内置的安全支持提供程序接口（Security Support Provider Interface，SSPI）实现 SPNEGO 单点登录认证（由 RFC4559 定义的方案），用于服务器的 Web 部分。SSPI 仅在 Windows 环境中工作，即当服务器和客户端都在 Windows 操作系统上运行时。
 在激活 SSPI 单点登录认证（SSO）之前，您需要准备您的环境:
 - 在 Active Directory 中创建一个单独的用户账户，gitea.exe 进程将在该账户下运行（例如，在 domain.local 域下创建一个名为 user 的账户:
 - 为运行 gitea.exe 的主机创建一个服务主体名称（Service Principal Name，SPN），其类别为 HTTP:
  - 以特权域用户（例如域管理员）的身份启动“命令提示符”或“PowerShell”。
  - 运行下面的命令，将 host.domain.local 替换为 Web 应用程序将运行的服务器的完全限定域名（FQDN），将 domain\user 替换为在前一步中创建的账户名称:
  ```sh
  setspn -A HTTP/host.domain.local domain\user
  ```
 在遵循上述步骤之前，请确保您按照以下流程进行操作:
 1. 用之前创建的用户登录（如果已经登录，请先注销）。
 2. 确保在`custom/conf/app.ini`文件的`[server]`部分中，`ROOT_URL`设置为 Web 应用程序将运行的服务器的完全限定域名（FQDN），与之前创建服务主体名称时使用的一致（例如，`host.domain.local`）。
 3. 启动 Web 服务器（运行 `gitea.exe web`）。
 4. 在 `Site Administration -> Authentication Sources` 中添加一个 `SPNEGO with SSPI` 认证源，以启用 SSPI 认证。
 5. 在域中的客户端计算机上，使用任何域用户登录（与运行`gitea.exe`的服务器不同）。
 6. 如果您使用 Chrome 或 Edge 浏览器，请将 Web 应用程序的 URL 添加到“本地站点”（`Internet选项 -> 安全 -> 本地站点 -> 站点`）。
 7. 启动 Chrome 或 Edge 浏览器，导航到 Gitea 的 FQDN URL（例如，`http://host.domain.local:3000`）。
 8. 在控制面板中点击“Sign In”按钮，然后选择 SSPI，将会自动使用当前登录到计算机的用户进行登录。
 9. 如果无法正常工作，请确保:
   - 您不是在运行`gitea.exe`的同一台服务器上运行 Web 浏览器。应该在与服务器不同的域加入计算机（客户端）上运行 Web 浏览器。如果客户端和服务器都在同一台计算机上运行，则 NTLM 将优先于 Kerberos。
   - 主机上只有一个`HTTP/...`的 SPN。
   - SPN 中只包含主机名，不包含端口号。
   - 将 Web 应用程序的 URL 添加到"本地站点"。
   - 服务器和客户端的时钟差异不超过 5 分钟（取决于组策略）。
   - 在 Internet Explorer 中启用了"集成 Windows 身份验证"（在"高级设置"下）。
 遵循这些步骤，您应该能够成功启用和使用 SSPI 单点登录认证（SSO）。
 ## 反向代理认证
 Gitea 支持通过读取反向代理传递的 HTTP 头中的登录名或者 email 地址来支持反向代理来认证。默认是不启用的，你可以用以下配置启用。
 ```ini
 [service]
 ENABLE_REVERSE_PROXY_AUTHENTICATION = true
 ```
 默认的登录用户名的 HTTP 头是 `X-WEBAUTH-USER`，你可以通过修改 `REVERSE_PROXY_AUTHENTICATION_USER` 来变更它。如果用户不存在，可以自动创建用户，当然你需要修改 `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=true` 来启用它。
 默认的登录用户 Email 的 HTTP 头是 `X-WEBAUTH-EMAIL`，你可以通过修改 `REVERSE_PROXY_AUTHENTICATION_EMAIL` 来变更它。如果用户不存在，可以自动创建用户，当然你需要修改 `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=true` 来启用它。你也可以通过修改 `ENABLE_REVERSE_PROXY_EMAIL` 来启用或停用这个 HTTP 头。
 如果设置了 `ENABLE_REVERSE_PROXY_FULL_NAME=true`，则用户的全名会从 `X-WEBAUTH-FULLNAME` 读取，这样在自动创建用户时将使用这个字段作为用户全名，你也可以通过修改 `REVERSE_PROXY_AUTHENTICATION_FULL_NAME` 来变更 HTTP 头。
 你也可以通过修改 `REVERSE_PROXY_TRUSTED_PROXIES` 来设置反向代理的 IP 地址范围，加强安全性，默认值是 `127.0.0.0/8,::1/128`。 通过 `REVERSE_PROXY_LIMIT`， 可以设置最多信任几级反向代理。
 你可以通过以下配置为 API 启用此认证方法：
 ```ini
 [service]
 ENABLE_REVERSE_PROXY_AUTHENTICATION_API = true
 ```
 :::note
 当此方法用于 API 时，反向代理负责处理 CSRF 保护。
 :::
@@ -1,146 +0,0 @@
 ---
 date: "2018-06-06T09:33:00+08:00"
 slug: "backup-and-restore"
 sidebar_position: 11
 aliases:
  - /zh-cn/backup-and-restore
 ---
 # 备份与恢复
 Gitea 已经实现了 `dump` 命令可以用来备份所有需要的文件到一个 zip 压缩文件。该压缩文件可以被用来进行数据恢复。
 ## 备份一致性
 为了确保 Gitea 实例的一致性，在备份期间必须关闭它。
 Gitea 包括数据库、文件和 Git 仓库，当它被使用时所有这些都会发生变化。例如，当迁移正在进行时，在数据库中创建一个事务，而 Git 仓库正在被复制。如果备份发生在迁移的中间，Git 仓库可能是不完整的，尽管数据库声称它是完整的，因为它是在之后被转储的。避免这种竞争条件的唯一方法是在备份期间停止 Gitea 实例。
 ## 备份命令 (`dump`)
 先转到 git 用户的权限: `su git`. 再 Gitea 目录运行 `./gitea dump`。一般会显示类似如下的输出：
 ```
 2016/12/27 22:32:09 Creating tmp work dir: /tmp/gitea-dump-417443001
 2016/12/27 22:32:09 Dumping local repositories.../home/git/repositories
 2016/12/27 22:32:22 Dumping database...
 2016/12/27 22:32:22 Packing dump files...
 2016/12/27 22:32:34 Removing tmp work dir: /tmp/gitea-dump-417443001
 2016/12/27 22:32:34 Finish dumping in file gitea-dump-1482906742.zip
 ```
 最后生成的 `gitea-dump-1482906742.zip` 文件将会包含如下内容：
 - `app.ini` - 如果原先存储在默认的 custom/ 目录之外，则是配置文件的可选副本
 - `custom/` - 所有保存在 `custom/` 目录下的配置和自定义的文件。
 - `data/` - 数据目录（APP_DATA_PATH），如果使用文件会话，则不包括会话。该目录包括 `attachments`、`avatars`、`lfs`、`indexers`、如果使用 SQLite 则包括 SQLite 文件。
 - `repos/` - 仓库目录的完整副本。
 - `gitea-db.sql` - 数据库 dump 出来的 SQL。
 - `log/` - Logs 文件，如果用作迁移不是必须的。
 中间备份文件将会在临时目录进行创建，如果您要重新指定临时目录，可以用 `--tempdir` 参数，或者用 `TMPDIR` 环境变量。
 ## 备份数据库
 `gitea dump` 创建的 SQL 转储使用 XORM，Gitea 管理员可能更喜欢使用本地的 MySQL 和 PostgreSQL 转储工具。使用 XORM 转储数据库时仍然存在一些问题，可能会导致在尝试恢复时出现问题。
 ```sh
 # mysql
 mysqldump -u$USER -p$PASS --databases $DATABASE > gitea-db.sql
 # postgres
 pg_dump -U $USER $DATABASE > gitea-db.sql
 ```
 ### 使用 Docker （`dump`）
 在使用 Docker 时，使用 `dump` 命令有一些注意事项。
 必须以 `gitea/conf/app.ini` 中指定的 `RUN_USER = <OS_USERNAME>` 执行该命令；并且，为了让备份文件夹的压缩过程能够顺利执行，`docker exec` 命令必须在 `--tempdir` 内部执行。
 示例：
 ```none
 docker exec -u <OS_USERNAME> -it -w <--tempdir> $(docker ps -qf 'name=^<NAME_OF_DOCKER_CONTAINER>$') bash -c '/usr/local/bin/gitea dump -c </path/to/app.ini>'
 ```
 \*注意：`--tempdir` 指的是 Gitea 使用的 Docker 环境的临时目录；如果您没有指定自定义的 `--tempdir`，那么 Gitea 将使用 `/tmp` 或 Docker 容器的 `TMPDIR` 环境变量。对于 `--tempdir`，请相应调整您的 `docker exec` 命令选项。
 结果应该是一个文件，存储在指定的 `--tempdir` 中，类似于：`gitea-dump-1482906742.zip`
 ## 恢复命令 (`restore`)
 当前还没有恢复命令，恢复需要人工进行。主要是把文件和数据库进行恢复。
 例如：
 ```sh
 unzip gitea-dump-1610949662.zip
 cd gitea-dump-1610949662
 mv app.ini /etc/gitea/conf/app.ini
 mv data/* /var/lib/gitea/data/
 mv log/* /var/lib/gitea/log/
 mv repos/* /var/lib/gitea/data/gitea-repositories/
 chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea
 # mysql
 mysql --default-character-set=utf8mb4 -u$USER -p$PASS $DATABASE <gitea-db.sql
 # sqlite3
 sqlite3 $DATABASE_PATH <gitea-db.sql
 # postgres
 psql -U $USER -d $DATABASE < gitea-db.sql
 service gitea restart
 ```
 如果安装方式发生了变化（例如 二进制 -> Docker），或者 Gitea 安装到了与之前安装不同的目录，则需要重新生成仓库 Git 钩子。
 在 Gitea 运行时，并从 Gitea 二进制文件所在的目录执行：`./gitea admin regenerate hooks`
 这样可以确保仓库 Git 钩子中的应用程序和配置文件路径与当前安装一致。如果这些路径没有更新，仓库的 `push` 操作将失败。
 ### 使用 Docker (`restore`)
 在基于 Docker 的 Gitea 实例中，也没有恢复命令的支持。恢复过程与前面描述的步骤相同，但路径不同。
 示例：
 ```sh
 # 在容器中打开 bash 会话
 docker exec --user git -it 2a83b293548e bash
 # 在容器内解压您的备份文件
 unzip gitea-dump-1610949662.zip
 cd gitea-dump-1610949662
 # 恢复 Gitea 数据
 mv data/* /data/gitea
 # 恢复仓库本身
 mv repos/* /data/git/repositories/
 # 调整文件权限
 chown -R git:git /data
 # 重新生成 Git 钩子
 /usr/local/bin/gitea -c '/data/gitea/conf/app.ini' admin regenerate hooks
 ```
 Gitea 容器中的默认用户是 `git`（1000:1000）。请用您的 Gitea 容器 ID 或名称替换 `2a83b293548e`。
 ### 使用 Docker-rootless (`restore`)
 在 Docker-rootless 容器中的恢复工作流程只是要使用的目录不同：
 ```sh
 # 在容器中打开 bash 会话
 docker exec --user git -it 2a83b293548e bash
 # 在容器内解压您的备份文件
 unzip gitea-dump-1610949662.zip
 cd gitea-dump-1610949662
 # 恢复 app.ini
 mv data/conf/app.ini /etc/gitea/app.ini
 # 恢复 Gitea 数据
 mv data/* /var/lib/gitea
 # 恢复仓库本身
 mv repos/* /var/lib/gitea/git/repositories
 # 调整文件权限
 chown -R git:git /etc/gitea/app.ini /var/lib/gitea
 # 重新生成 Git 钩子
 /usr/local/bin/gitea -c '/etc/gitea/app.ini' admin regenerate hooks
 ```
@@ -1,93 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 slug: "cmd-embedded"
 sidebar_position: 20
 aliases:
  - /zh-cn/cmd-embedded
 ---
 # 嵌入资源提取工具
 Gitea 的可执行文件包含了运行所需的所有资源：模板、图片、样式表和翻译文件。你可以通过在 `custom` 目录下的相应路径中放置替换文件来覆盖其中的任何资源（详见 [自定义 Gitea 配置](../administration/customizing-gitea.md)）。
 要获取嵌入资源的副本以进行编辑，可以使用 CLI 中的 `embedded` 命令，通过操作系统的 shell 执行。
 **注意：** 嵌入资源提取工具包含在 Gitea 1.12 及以上版本中。
 ## 资源列表
 要列出嵌入在 Gitea 可执行文件中的资源，请使用以下语法：
 ```sh
 gitea embedded list [--include-vendored] [patterns...]
 ```
 `--include-vendored` 标志使命令包括被供应的文件，这些文件通常被排除在外；即来自外部库的文件，这些文件是 Gitea 所需的（例如 [octicons](https://octicons.github.com/) 等）。
 可以提供一系列文件搜索模式。Gitea 使用 [gobwas/glob](https://github.com/gobwas/glob) 作为其 glob 语法。以下是一些示例：
 - 列出所有模板文件，无论在哪个虚拟目录下：`**.tmpl`
 - 列出所有邮件模板文件：`templates/mail/**.tmpl`
  列出 `public/assets/img` 目录下的所有文件：`public/assets/img/**`
 不要忘记为模式使用引号，因为空格、`*` 和其他字符可能对命令行解释器有特殊含义。
 如果未提供模式，则列出所有文件。
 ### 示例：列出所有嵌入文件
 列出所有路径中包含 `openid` 的嵌入文件：
 ```sh
 $ gitea embedded list '**openid**'
 public/assets/img/auth/openid_connect.svg
 public/assets/img/openid-16x16.png
 templates/user/auth/finalize_openid.tmpl
 templates/user/auth/signin_openid.tmpl
 templates/user/auth/signup_openid_connect.tmpl
 templates/user/auth/signup_openid_navbar.tmpl
 templates/user/auth/signup_openid_register.tmpl
 templates/user/settings/security_openid.tmpl
 ```
 ## 提取资源
 要提取嵌入在 Gitea 可执行文件中的资源，请使用以下语法：
 ```sh
 gitea [--config {file}] embedded extract [--destination {dir}|--custom] [--overwrite|--rename] [--include-vendored] {patterns...}
 ```
 `--config` 选项用于告知 Gitea `app.ini` 配置文件的位置（如果不在默认位置）。此选项仅在使用 `--custom` 标志时使用。
 `--destination` 选项用于指定提取文件的目标目录。默认为当前目录。
 `--custom` 标志告知 Gitea 直接将文件提取到 `custom` 目录中。为使其正常工作，该命令需要知道 `app.ini` 配置文件的位置（通过 `--config` 指定），并且根据配置的不同，需要从 Gitea 通常启动的目录运行。有关详细信息，请参阅 [自定义 Gitea 配置](../administration/customizing-gitea.md)。
 `--overwrite` 标志允许覆盖目标目录中的任何现有文件。
 `--rename` 标志告知 Gitea 将目标目录中的任何现有文件重命名为 `filename.bak`。之前的 `.bak` 文件将被覆盖。
 至少需要提供一个文件搜索模式；有关模式的语法和示例，请参阅上述 `list` 子命令。
 ### 重要提示
 请确保**只提取需要自定义的文件**。位于 `custom` 目录中的文件不会受到 Gitea 的升级过程的影响。当 Gitea 升级到新版本（通过替换可执行文件）时，许多嵌入文件将发生变化。Gitea 将尊重并使用在 `custom` 目录中找到的任何文件，即使这些文件是旧的和不兼容的。
 ### 示例：提取邮件模板
 将邮件模板提取到临时目录：
 ```sh
 $ mkdir tempdir
 $ gitea embedded extract --destination tempdir 'templates/mail/**.tmpl'
 Extracting to tempdir:
 tempdir/templates/mail/auth/activate.tmpl
 tempdir/templates/mail/auth/activate_email.tmpl
 tempdir/templates/mail/auth/register_notify.tmpl
 tempdir/templates/mail/auth/reset_passwd.tmpl
 tempdir/templates/mail/issue/assigned.tmpl
 tempdir/templates/mail/issue/default.tmpl
 tempdir/templates/mail/notify/collaborator.tmpl
 ```
@@ -1,534 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 slug: "command-line"
 sidebar_position: 1
 aliases:
  - /zh-cn/command-line
 ---
 # 命令行
 ## 用法
 `gitea [全局选项] 命令 [命令或全局选项] [参数...]`
 ## 全局选项
 所有全局选项均可被放置在命令级别。
 - `--help`，`-h`：显示帮助文本并退出。可选。
 - `--version`，`-v`：显示版本信息并退出。可选。 (示例：`Gitea version 1.1.0+218-g7b907ed built with: bindata, sqlite`)。
 - `--custom-path path`，`-C path`：Gitea 自定义文件夹的路径。可选。 (默认值：`AppWorkPath`/custom 或 `$GITEA_CUSTOM`)。
 - `--config path`，`-c path`：Gitea 配置文件的路径。可选。 (默认值：`custom`/conf/app.ini)。
 - `--work-path path`，`-w path`：Gitea 的 `AppWorkPath`。可选。 (默认值：LOCATION_OF_GITEA_BINARY 或 `$GITEA_WORK_DIR`)
 注意：默认的 custom-path、config 和 work-path 也可以在构建时更改（如果需要）。
 ## 命令
 ### web
 启动服务器：
 - 选项：
  - `--port number`，`-p number`：端口号。可选。 (默认值：3000)。覆盖配置文件中的设置。
  - `--install-port number`：运行安装页面的端口号。可选。 (默认值：3000)。覆盖配置文件中的设置。
  - `--pid path`，`-P path`：Pid 文件的路径。可选。
  - `--quiet`，`-q`：只在控制台上输出 Fatal 日志，用于在设置日志之前发出的日志。
  - `--verbose`：在控制台上输出跟踪日志，用于在设置日志之前发出的日志。
 - 示例：
  - `gitea web`
  - `gitea web --port 80`
  - `gitea web --config /etc/gitea.ini --pid /some/custom/gitea.pid`
 - 注意：
  - Gitea 不应以 root 用户身份运行。要绑定到低于 1024 的端口，您可以在 Linux 上使用 setcap 命令：`sudo setcap 'cap_net_bind_service=+ep' /path/to/gitea`。每次更新 Gitea 都需要重新执行此操作。
 ### admin
 管理员操作：
 - 命令：
  - `user`：
    - `list`：
      - 选项：
        - `--admin`：仅列出管理员用户。可选。
      - 描述：列出所有现有用户。
      - 示例：
        - `gitea admin user list`
    - `delete`：
      - 选项：
        - `--email`：要删除的用户的电子邮件。
        - `--username`：要删除的用户的用户名。
        - `--id`：要删除的用户的 ID。
        - 必须提供 `--id`、`--username` 或 `--email` 中的一个。如果提供多个，则所有条件必须匹配。
      - 示例：
        - `gitea admin user delete --id 1`
    - `create`：
      - 选项：
        - `--name value`：用户名。必填。自 Gitea 1.9.0 版本起，请改用 `--username` 标志。
        - `--username value`：用户名。必填。Gitea 1.9.0 新增。
        - `--password value`：密码。必填。
        - `--email value`：邮箱。必填。
        - `--admin`：如果提供此选项，将创建一个管理员用户。可选。
        - `--access-token`：如果提供，将为用户创建访问令牌。可选。（默认值：false）。
        - `--must-change-password`：如果提供，创建的用户将在初始登录后需要选择一个新密码。可选。（默认值：true）。
        - `--random-password`：如果提供，将使用随机生成的密码作为创建用户的密码。`--password` 的值将被忽略。可选。
        - `--random-password-length`：如果提供，将用于配置随机生成密码的长度。可选。（默认值：12）
      - 示例：
        - `gitea admin user create --username myname --password asecurepassword --email [email protected]`
    - `change-password`：
      - 选项：
        - `--username value`，`-u value`：用户名。必填。
        - `--password value`，`-p value`：新密码。必填。
      - 示例：
        - `gitea admin user change-password --username myname --password asecurepassword`
    - `must-change-password`：
      - 参数：
        - `[username...]`：需要更改密码的用户
      - 选项：
        - `--all`，`-A`：强制所有用户更改密码
        - `--exclude username`，`-e username`：排除给定的用户。可以多次设置。
        - `--unset`：撤销对给定用户的强制密码更改
  - `regenerate`：
    - 选项：
      - `hooks`：重新生成所有仓库的 Git Hooks。
      - `keys`：重新生成 authorized_keys 文件。
    - 示例：
      - `gitea admin regenerate hooks`
      - `gitea admin regenerate keys`
  - `auth`：
    - `list`：
      - 描述：列出所有存在的外部认证源。
      - 示例：
        - `gitea admin auth list`
    - `delete`：
      - 选项：
        - `--id`：要删除的源的 ID。必填。
      - 示例：
        - `gitea admin auth delete --id 1`
    - `add-oauth`：
      - 选项：
        - `--name`：应用程序名称。
        - `--provider`：OAuth2 提供者。
        - `--key`：客户端 ID（Key）。
        - `--secret`：客户端密钥。
        - `--auto-discover-url`：OpenID Connect 自动发现 URL（仅在使用 OpenID Connect 作为提供程序时需要）。
        - `--use-custom-urls`：在 GitLab/GitHub OAuth 端点上使用自定义 URL。
        - `--custom-tenant-id`：在 OAuth 端点上使用自定义租户 ID。
        - `--custom-auth-url`：使用自定义授权 URL（GitLab/GitHub 的选项）。
        - `--custom-token-url`：使用自定义令牌 URL（GitLab/GitHub 的选项）。
        - `--custom-profile-url`：使用自定义配置文件 URL（GitLab/GitHub 的选项）。
        - `--custom-email-url`：使用自定义电子邮件 URL（GitHub 的选项）。
        - `--icon-url`：OAuth2 登录源的自定义图标 URL。
        - `--skip-local-2fa`：允许源覆盖本地 2FA。（可选）
        - `--scopes`：请求此 OAuth2 源的附加范围。（可选）
        - `--required-claim-name`：必须设置的声明名称，以允许用户使用此源登录。（可选）
        - `--required-claim-value`：必须设置的声明值，以允许用户使用此源登录。（可选）
        - `--group-claim-name`：提供此源的组名的声明名称。（可选）
        - `--admin-group`：管理员用户的组声明值。（可选）
        - `--restricted-group`：受限用户的组声明值。（可选）
        - `--group-team-map`：组与组织团队之间的 JSON 映射。（可选）
        - `--group-team-map-removal`：根据组自动激活团队成员资格的删除。（可选）
      - 示例：
        - `gitea admin auth add-oauth --name external-github --provider github --key OBTAIN_FROM_SOURCE --secret OBTAIN_FROM_SOURCE`
    - `update-oauth`：
      - 选项：
        - `--id`：要更新的源的 ID。必填。
        - `--name`：应用程序名称。
        - `--provider`：OAuth2 提供者。
        - `--key`：客户端 ID（Key）。
        - `--secret`：客户端密钥。
        - `--auto-discover-url`：OpenID Connect 自动发现 URL（仅在使用 OpenID Connect 作为提供程序时需要）。
        - `--use-custom-urls`：在 GitLab/GitHub OAuth 端点上使用自定义 URL。
        - `--custom-tenant-id`：在 OAuth 端点上使用自定义租户 ID。
        - `--custom-auth-url`：使用自定义授权 URL（GitLab/GitHub 的选项）。
        - `--custom-token-url`：使用自定义令牌 URL（GitLab/GitHub 的选项）。
        - `--custom-profile-url`：使用自定义配置文件 URL（GitLab/GitHub 的选项）。
        - `--custom-email-url`：使用自定义电子邮件 URL（GitHub 的选项）。
        - `--icon-url`：OAuth2 登录源的自定义图标 URL。
        - `--skip-local-2fa`：允许源覆盖本地 2FA。（可选）
        - `--scopes`：请求此 OAuth2 源的附加范围。
        - `--required-claim-name`：必须设置的声明名称，以允许用户使用此源登录。（可选）
        - `--required-claim-value`：必须设置的声明值，以允许用户使用此源登录。（可选）
        - `--group-claim-name`：提供此源的组名的声明名称。（可选）
        - `--admin-group`：管理员用户的组声明值。（可选）
        - `--restricted-group`：受限用户的组声明值。（可选）
      - 示例：
        - `gitea admin auth update-oauth --id 1 --name external-github-updated`
    - `add-smtp`：
      - 选项：
        - `--name`：应用程序名称。必填。
        - `--auth-type`：SMTP 认证类型（PLAIN/LOGIN/CRAM-MD5）。默认为 PLAIN。
        - `--host`：SMTP 主机。必填。
        - `--port`：SMTP 端口。必填。
        - `--force-smtps`：SMTPS 始终在端口 465 上使用。设置此选项以强制在其他端口上使用 SMTPS。
        - `--skip-verify`：跳过 TLS 验证。
        - `--helo-hostname`：发送 HELO 时使用的主机名。留空以发送当前主机名。
        - `--disable-helo`：禁用 SMTP helo。
        - `--allowed-domains`：留空以允许所有域。使用逗号（','）分隔多个域。
        - `--skip-local-2fa`：跳过 2FA 登录。
        - `--active`：启用此认证源。
          备注：
          `--force-smtps`、`--skip-verify`、`--disable-helo`、`--skip-local-2fs` 和 `--active` 选项可以采用以下形式使用：
        - `--option`、`--option=true` 以启用选项
        - `--option=false` 以禁用选项
          如果未指定这些选项，则在 `update-smtp` 中不会更改值，或者在 `add-smtp` 中将使用默认的 `false` 值。
      - 示例：
        - `gitea admin auth add-smtp --name ldap --host smtp.mydomain.org --port 587 --skip-verify --active`
    - `update-smtp`：
      - 选项：
        - `--id`：要更新的源的 ID。必填。
        - 其他选项与 `add-smtp` 共享
      - 示例：
        - `gitea admin auth update-smtp --id 1 --host smtp.mydomain.org --port 587 --skip-verify=false`
        - `gitea admin auth update-smtp --id 1 --active=false`
    - `add-ldap`：添加新的 LDAP（通过 Bind DN）认证源
      - 选项：
        - `--name value`：认证名称。必填。
        - `--not-active`：停用认证源。
        - `--security-protocol value`：安全协议名称。必填。
        - `--skip-tls-verify`：禁用 TLS 验证。
        - `--host value`：LDAP 服务器的地址。必填。
        - `--port value`：连接到 LDAP 服务器时使用的端口。必填。
        - `--user-search-base value`：用户帐户将在其中搜索的 LDAP 基础路径。必填。
        - `--user-filter value`：声明如何查找试图进行身份验证的用户记录的 LDAP 过滤器。必填。
        - `--admin-filter value`：指定是否应授予用户管理员特权的 LDAP 过滤器。
        - `--restricted-filter value`：指定是否应将用户设置为受限状态的 LDAP 过滤器。
        - `--username-attribute value`：用户 LDAP 记录中包含用户名的属性。
        - `--firstname-attribute value`：用户 LDAP 记录中包含用户名字的属性。
        - `--surname-attribute value`：用户 LDAP 记录中包含用户姓氏的属性。
        - `--email-attribute value`：用户 LDAP 记录中包含用户电子邮件地址的属性。必填。
        - `--public-ssh-key-attribute value`：用户 LDAP 记录中包含用户公共 SSH 密钥的属性。
        - `--avatar-attribute value`：用户 LDAP 记录中包含用户头像的属性。
        - `--bind-dn value`：在搜索用户时绑定到 LDAP 服务器的 DN。
        - `--bind-password value`：绑定 DN 的密码（如果有）。
        - `--attributes-in-bind`：在绑定 DN 上下文中获取属性。
        - `--synchronize-users`：启用用户同步。
        - `--page-size value`：搜索页面大小。
      - 示例：
        - `gitea admin auth add-ldap --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-search-base "ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))" --email-attribute mail`
    - `update-ldap`：更新现有的 LDAP（通过 Bind DN）认证源
      - 选项：
        - `--id value`：认证源的 ID。必填。
        - `--name value`：认证名称。
        - `--not-active`：停用认证源。
        - `--security-protocol value`：安全协议名称。
        - `--skip-tls-verify`：禁用 TLS 验证。
        - `--host value`：LDAP 服务器的地址。
        - `--port value`：连接到 LDAP 服务器时使用的端口。
        - `--user-search-base value`：用户帐户将在其中搜索的 LDAP 基础路径。
        - `--user-filter value`：声明如何查找试图进行身份验证的用户记录的 LDAP 过滤器。
        - `--admin-filter value`：指定是否应授予用户管理员特权的 LDAP 过滤器。
        - `--restricted-filter value`：指定是否应将用户设置为受限状态的 LDAP 过滤器。
        - `--username-attribute value`：用户 LDAP 记录中包含用户名的属性。
        - `--firstname-attribute value`：用户 LDAP 记录中包含用户名字的属性。
        - `--surname-attribute value`：用户 LDAP 记录中包含用户姓氏的属性。
        - `--email-attribute value`：用户 LDAP 记录中包含用户电子邮件地址的属性。
        - `--public-ssh-key-attribute value`：用户 LDAP 记录中包含用户公共 SSH 密钥的属性。
        - `--avatar-attribute value`：用户 LDAP 记录中包含用户头像的属性。
        - `--bind-dn value`：在搜索用户时绑定到 LDAP 服务器的 DN。
        - `--bind-password value`：绑定 DN 的密码（如果有）。
        - `--attributes-in-bind`：在绑定 DN 上下文中获取属性。
        - `--synchronize-users`：启用用户同步。
        - `--page-size value`：搜索页面大小。
      - 示例：
        - `gitea admin auth update-ldap --id 1 --name "my ldap auth source"`
        - `gitea admin auth update-ldap --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn`
    - `add-ldap-simple`：添加新的 LDAP（简单身份验证）认证源
      - 选项：
        - `--name value`：认证名称。必填。
        - `--not-active`：停用认证源。
        - `--security-protocol value`：安全协议名称。必填。
        - `--skip-tls-verify`：禁用 TLS 验证。
        - `--host value`：LDAP 服务器的地址。必填。
        - `--port value`：连接到 LDAP 服务器时使用的端口。必填。
        - `--user-search-base value`：用户帐户将在其中搜索的 LDAP 基础路径。
        - `--user-filter value`：声明如何查找试图进行身份验证的用户记录的 LDAP 过滤器。必填。
        - `--admin-filter value`：指定是否应授予用户管理员特权的 LDAP 过滤器。
        - `--restricted-filter value`：指定是否应将用户设置为受限状态的 LDAP 过滤器。
        - `--username-attribute value`：用户 LDAP 记录中包含用户名的属性。
        - `--firstname-attribute value`：用户 LDAP 记录中包含用户名字的属性。
        - `--surname-attribute value`：用户 LDAP 记录中包含用户姓氏的属性。
        - `--email-attribute value`：用户 LDAP 记录中包含用户电子邮件地址的属性。必填。
        - `--public-ssh-key-attribute value`：用户 LDAP 记录中包含用户公共 SSH 密钥的属性。
        - `--avatar-attribute value`：用户 LDAP 记录中包含用户头像的属性。
        - `--user-dn value`：用户的 DN。必填。
      - 示例：
        - `gitea admin auth add-ldap-simple --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-dn "cn=%s,ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(cn=%s))" --email-attribute mail`
    - `update-ldap-simple`：更新现有的 LDAP（简单身份验证）认证源
      - 选项：
        - `--id value`：认证源的 ID。必填。
        - `--name value`：认证名称。
        - `--not-active`：停用认证源。
        - `--security-protocol value`：安全协议名称。
        - `--skip-tls-verify`：禁用 TLS 验证。
        - `--host value`：LDAP 服务器的地址。
        - `--port value`：连接到 LDAP 服务器时使用的端口。
        - `--user-search-base value`：用户帐户将在其中搜索的 LDAP 基础路径。
        - `--user-filter value`：声明如何查找试图进行身份验证的用户记录的 LDAP 过滤器。
        - `--admin-filter value`：指定是否应授予用户管理员特权的 LDAP 过滤器。
        - `--restricted-filter value`：指定是否应将用户设置为受限状态的 LDAP 过滤器。
        - `--username-attribute value`：用户 LDAP 记录中包含用户名的属性。
        - `--firstname-attribute value`：用户 LDAP 记录中包含用户名字的属性。
        - `--surname-attribute value`：用户 LDAP 记录中包含用户姓氏的属性。
        - `--email-attribute value`：用户 LDAP 记录中包含用户电子邮件地址的属性。
        - `--public-ssh-key-attribute value`：用户 LDAP 记录中包含用户公共 SSH 密钥的属性。
        - `--avatar-attribute value`：用户 LDAP 记录中包含用户头像的属性。
        - `--user-dn value`：用户的 DN。
      - 示例：
        - `gitea admin auth update-ldap-simple --id 1 --name "my ldap auth source"`
        - `gitea admin auth update-ldap-simple --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn`
 ### cert
 生成自签名的 SSL 证书。将输出到当前目录下的`cert.pem`和`key.pem`文件中，并且会覆盖任何现有文件。
 - 选项：
  - `--host value`：逗号分隔的主机名和 IP 地址列表，此证书适用于这些主机。支持使用通配符。必填。
  - `--ecdsa-curve value`：用于生成密钥的 ECDSA 曲线。可选。有效选项为 P224、P256、P384、P521。
  - `--rsa-bits value`：要生成的 RSA 密钥的大小。可选。如果设置了--ecdsa-curve，则忽略此选项。（默认值：3072）。
  - `--start-date value`：证书的创建日期。可选。（格式：`Jan 1 15:04:05 2011`）。
  - `--duration value`：证书有效期。可选。（默认值：8760h0m0s）
  - `--ca`：如果提供此选项，则证书将生成自己的证书颁发机构。可选。
 - 示例：
  - `gitea cert --host git.example.com,example.com,www.example.com --ca`
 ### dump
 将所有文件和数据库导出到一个 zip 文件中。输出文件将保存在当前目录下，类似于`gitea-dump-1482906742.zip`。
 - 选项：
  - `--file name`，`-f name`：指定要创建的导出文件的名称。可选。（默认值：gitea-dump-[timestamp].zip）。
  - `--tempdir path`，`-t path`：指定临时目录的路径。可选。（默认值：/tmp）。
  - `--skip-repository`，`-R`：跳过仓库的导出。可选。
  - `--skip-custom-dir`：跳过自定义目录的导出。可选。
  - `--skip-lfs-data`：跳过 LFS 数据的导出。可选。
  - `--skip-attachment-data`：跳过附件数据的导出。可选。
  - `--skip-package-data`：跳过包数据的导出。可选。
  - `--skip-log`：跳过日志数据的导出。可选。
  - `--database`，`-d`：指定数据库的 SQL 语法。可选。
  - `--verbose`，`-V`：如果提供此选项，显示附加详细信息。可选。
  - `--type`：设置导出的格式。可选。（默认值：zip）
 - 示例：
  - `gitea dump`
  - `gitea dump --verbose`
 ### generate
 用于在配置文件中生成随机值和令牌。对于自动部署时生成值非常有用。
 - 命令:
  - `secret`:
    - 选项:
      - `INTERNAL_TOKEN`: 用于内部 API 调用身份验证的令牌。
      - `JWT_SECRET`: 用于 LFS 和 OAUTH2 JWT 身份验证的密钥（LFS_JWT_SECRET 是此选项的别名，用于向后兼容）。
      - `SECRET_KEY`: 全局密钥。
    - 示例:
      - `gitea generate secret INTERNAL_TOKEN`
      - `gitea generate secret JWT_SECRET`
      - `gitea generate secret SECRET_KEY`
 ### keys
 提供一个 SSHD AuthorizedKeysCommand。需要在 sshd 配置文件中进行配置:
 ```ini
 ...
 # -e 的值和 AuthorizedKeysCommandUser 应与运行 Gitea 的用户名匹配
 AuthorizedKeysCommandUser git
 AuthorizedKeysCommand /path/to/gitea keys -e git -u %u -t %t -k %k
 ```
 该命令将返回适用于提供的密钥的合适 authorized_keys 行。您还应在 `app.ini` 的 `[server]` 部分设置值 `SSH_CREATE_AUTHORIZED_KEYS_FILE=false`。
 注意: opensshd 要求 Gitea 程序由 root 拥有，并且不可由组或其他人写入。程序必须使用绝对路径指定。
 注意: Gitea 必须在运行此命令时处于运行状态才能成功。
 ### migrate
 迁移数据库。该命令可用于在首次启动服务器之前运行其他命令。此命令是幂等的。
 ### doctor check
 对 Gitea 实例进行诊断，可以修复一些可修复的问题。
 默认只运行部分检查，额外的检查可以参考：
 - `gitea doctor check --list` - 列出所有可用的检查
 - `gitea doctor check --all` - 运行所有可用的检查
 - `gitea doctor check --default` - 运行默认的检查
 - `gitea doctor check --run [check(s),]...` - 运行指定的名字的检查
 有些问题可以通过设置 `--fix` 选项进行自动修复。
 额外的日志可以通过 `--log-file=...` 进行设置。
 #### doctor recreate-table
 有时，在迁移时，旧的列和默认值可能会在数据库模式中保持不变。这可能会导致警告，如下所示:
 ```
 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 doctor recreate-table table1 table2 ...
 ```
 如果您希望 Gitea 重新创建所有表，请直接调用：
 ```
 gitea doctor recreate-table
 ```
 强烈建议在运行这些命令之前备份您的数据库。
 ### doctor convert
 将现有的 MySQL 数据库从 utf8 转换为 utf8mb4，或者把 MSSQL 数据库从 varchar 转换为 nvarchar。
 ### manager
 管理运行中的服务器操作：
 - 命令:
  - `shutdown`: 优雅地关闭运行中的进程
  - `restart`: 优雅地重新启动运行中的进程（对于 Windows 服务器尚未实现）
  - `flush-queues`: 刷新运行中的进程中的队列
    - 选项:
      - `--timeout value`: 刷新过程的超时时间（默认值: 1m0s）
      - `--non-blocking`: 设置为 true，以在返回之前不等待刷新完成
  - `logging`: 调整日志命令
    - 命令:
      - `pause`: 暂停日志记录
        - 注意:
          - 如果日志级别低于此级别，日志级别将被临时提升为 INFO。
          - Gitea 将在一定程度上缓冲日志，并在超过该点后丢弃日志。
      - `resume`: 恢复日志记录
      - `release-and-reopen`: 使 Gitea 释放和重新打开用于日志记录的文件和连接（相当于向 Gitea 发送 SIGUSR1 信号）。
      - `remove name`: 删除指定的日志记录器
        - 选项:
          - `--group group`, `-g group`: 从中删除子记录器的组（默认为`default`）
      - `add`: 添加日志记录器
        - 命令:
          - `console`: 添加控制台日志记录器
            - 选项:
              - `--group value`, `-g value`: 要添加日志记录器的组 - 默认为"default"
              - `--name value`, `-n value`: 新日志记录器的名称 - 默认为模式
              - `--level value`, `-l value`: 新日志记录器的日志级别
              - `--stacktrace-level value`, `-L value`: 堆栈跟踪日志级别
              - `--flags value`, `-F value`: 日志记录器的标志
              - `--expression value`, `-e value`: 日志记录器的匹配表达式
              - `--prefix value`, `-p value`: 日志记录器的前缀
              - `--color`: 在日志中使用颜色
              - `--stderr`: 将控制台日志输出到 stderr - 仅适用于控制台
          - `file`: 添加文件日志记录器
            - 选项:
              - `--group value`, `-g value`: 要添加日志记录器的组 - 默认为"default"
              - `--name value`, `-n value`: 新日志记录器的名称 - 默认为模式
              - `--level value`, `-l value`: 新日志记录器的日志级别
              - `--stacktrace-level value`, `-L value`: 堆栈跟踪日志级别
              - `--flags value`, `-F value`: 日志记录器的标志
              - `--expression value`, `-e value`: 日志记录器的匹配表达式
              - `--prefix value`, `-p value`: 日志记录器的前缀
              - `--color`: 在日志中使用颜色
              - `--filename value`, `-f value`: 日志记录器的文件名
              - `--rotate`, `-r`: 轮转日志
              - `--max-size value`, `-s value`: 在轮转之前的最大大小（以字节为单位）
              - `--daily`, `-d`: 每天轮转日志
              - `--max-days value`, `-D value`: 保留的每日日志的最大数量
              - `--compress`, `-z`: 压缩轮转的日志
              - `--compression-level value`, `-Z value`: 使用的压缩级别
          - `conn`: 添加网络连接日志记录器
            - 选项:
              - `--group value`, `-g value`: 要添加日志记录器的组 - 默认为"default"
              - `--name value`, `-n value`: 新日志记录器的名称 - 默认为模式
              - `--level value`, `-l value`: 新日志记录器的日志级别
              - `--stacktrace-level value`, `-L value`: 堆栈跟踪日志级别
              - `--flags value`, `-F value`: 日志记录器的标志
              - `--expression value`, `-e value`: 日志记录器的匹配表达式
              - `--prefix value`, `-p value`: 日志记录器的前缀
              - `--color`: 在日志中使用颜色
              - `--reconnect-on-message`, `-R`: 对于每个消息重新连接主机
              - `--reconnect`, `-r`: 连接中断时重新连接主机
              - `--protocol value`, `-P value`: 设置要使用的协议：tcp、unix 或 udp（默认为 tcp）
              - `--address value`, `-a value`: 要连接到的主机地址和端口（默认为:7020）
          - `smtp`: 添加 SMTP 日志记录器
            - 选项:
              - `--group value`, `-g value`: 要添加日志记录器的组 - 默认为"default"
              - `--name value`, `-n value`: 新日志记录器的名称 - 默认为模式
              - `--level value`, `-l value`: 新日志记录器的日志级别
              - `--stacktrace-level value`, `-L value`: 堆栈跟踪日志级别
              - `--flags value`, `-F value`: 日志记录器的标志
              - `--expression value`, `-e value`: 日志记录器的匹配表达式
              - `--prefix value`, `-p value`: 日志记录器的前缀
              - `--color`: 在日志中使用颜色
              - `--username value`, `-u value`: 邮件服务器用户名
              - `--password value`, `-P value`: 邮件服务器密码
              - `--host value`, `-H value`: 邮件服务器主机（默认为: 127.0.0.1:25）
              - `--send-to value`, `-s value`: 要发送到的电子邮件地址
              - `--subject value`, `-S value`: 发送电子邮件的主题标题
  - `processes`: 显示 Gitea 进程和 Goroutine 信息
    - 选项:
      - `--flat`: 以平面表格形式显示进程，而不是树形结构
      - `--no-system`: 不显示系统进程
      - `--stacktraces`: 显示与进程关联的 Goroutine 的堆栈跟踪
      - `--json`: 输出为 JSON 格式
      - `--cancel PID`: 向具有 PID 的进程发送取消命令（仅适用于非系统进程）
 ### dump-repo
 `dump-repo` 从 Git/GitHub/Gitea/GitLab 中转储存储库数据：
 - 选项：
  - `--git_service service`：Git 服务，可以是 `git`、`github`、`gitea`、`gitlab`。如果 `clone_addr` 可以被识别，则可以忽略此选项。
  - `--repo_dir dir`，`-r dir`：存储数据的存储库目录路径。
  - `--clone_addr addr`：将被克隆的 URL，目前可以是 git/github/gitea/gitlab 的 http/https URL。例如：https://github.com/lunny/tango.git
  - `--auth_username lunny`：访问 `clone_addr` 的用户名。
  - `--auth_password <password>`：访问 `clone_addr` 的密码。
  - `--auth_token <token>`：访问 `clone_addr` 的个人令牌。
  - `--owner_name lunny`：如果非空，数据将存储在具有所有者名称的目录中。
  - `--repo_name tango`：如果非空，数据将存储在具有存储库名称的目录中。
  - `--units <units>`：要迁移的项目，一个或多个项目应以逗号分隔。允许的项目有 wiki, issues, labels, releases, release_assets, milestones, pull_requests, comments。如果为空，则表示所有项目。
 ### restore-repo
 `restore-repo` 从磁盘目录中还原存储库数据：
 - 选项：
  - `--repo_dir dir`，`-r dir`：还原数据的存储库目录路径。
  - `--owner_name lunny`：还原目标所有者名称。
  - `--repo_name tango`：还原目标存储库名称。
  - `--units <units>`：要还原的项目，一个或多个项目应以逗号分隔。允许的项目有 wiki, issues, labels, releases, release_assets, milestones, pull_requests, comments。如果为空，则表示所有项目。
 ### actions generate-runner-token
 生成一个供 Runner 使用的新令牌，用于向服务器注册。
 - 选项：
  - `--scope {owner}[/{repo}]`，`-s {owner}[/{repo}]`：限制 Runner 的范围，没有范围表示该 Runner 可用于所有仓库，但你也可以将其限制为特定的仓库或所有者。
 要注册全局 Runner：
 ```
 gitea actions generate-runner-token
 ```
 要注册特定组织的 Runner，例如 `org`：
 ```
 gitea actions generate-runner-token -s org
 ```
 要注册特定仓库的 Runner，例如 `username/test-repo`：
 ```
 gitea actions generate-runner-token -s username/test-repo
 ```
@@ -1,547 +0,0 @@
 ---
 date: "2017-04-15T14:56:00+02:00"
 slug: "customizing-gitea"
 sidebar_position: 100
 aliases:
  - /zh-cn/customizing-gitea
 ---
 # 自定义 Gitea
 自定义 Gitea 通常通过 `CustomPath` 目录完成。默认情况下，它是工作目录（WorkPath）下的
 `custom` 目录，但如果您的[安装方式](../installation/from-binary.md)做了不同设置，也可能位于其他位置。
 这是覆盖配置项、模板等内容的核心位置。您可以通过 `gitea help` 查看 `CustomPath`，也可以在
 _站点管理_ 页面的 _Configuration_ 选项卡中找到该路径。您还可以通过设置 `GITEA_CUSTOM`
 环境变量，或在 `gitea` 二进制上使用 `--custom-path` 选项来覆盖 `CustomPath`。
 （命令行选项会覆盖环境变量。）
 如果 Gitea 以二进制方式部署，所有默认路径都相对于 Gitea 二进制文件。
 如果通过发行版安装，这些路径通常会按照 Linux 文件系统标准进行调整。Gitea 会尝试创建所需目录，
 包括 `custom/`。某些发行版可能会通过 `/etc/gitea/` 为 `custom` 提供一个符号链接。
 应用配置可以在 `CustomConf` 文件中找到，默认路径为 `$GITEA_CUSTOM/conf/app.ini`，
 但如果您的[安装方式](../installation/from-binary.md)修改了配置，也可能位于其他位置。
 同样，您可以通过 `gitea help` 查看该变量，也可以使用 `gitea` 二进制的 `--config` 选项覆盖它。
 - [快速备忘单](../administration/config-cheat-sheet.md)
 - [完整配置清单](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini)
 如果在检查 `gitea help` 后仍找不到 `CustomPath` 目录，请检查 `GITEA_CUSTOM` 环境变量；
 它可以用来将默认路径覆盖为其他位置。例如，`GITEA_CUSTOM` 可能由 init 脚本设置。
 您也可以在站点管理页面的 “Configuration” 选项卡下检查该值是否已设置。
 - [环境变量清单](../administration/environment-variables.md)
 :::note
 Gitea 必须执行完整重启后，配置更改才会生效。
 :::
 ## 提供自定义公共文件
 要让 Gitea 提供自定义公共文件（例如页面和图片），请将 `$GITEA_CUSTOM/public/`
 目录作为 webroot。Gitea 会跟随符号链接。
 当前仅提供以下文件：
 - `public/robots.txt`
 - `public/.well-known/` 目录中的文件
 - `public/assets/` 目录中的文件
 例如，存放在 `$GITEA_CUSTOM/public/assets/` 中的 `image.png` 文件，可以通过
 `http://gitea.domain.tld/assets/image.png` 访问。
 ## 修改 Logo
 如果要构建自定义 logo 和/或 favicon，请克隆 Gitea 源码仓库，替换 `assets/logo.svg`
 和/或 `assets/favicon.svg`，然后运行 `make generate-images`。`assets/favicon.svg`
 仅用于 favicon。执行后会更新以下输出文件，随后您可以将它们放到服务器上的
 `$GITEA_CUSTOM/public/assets/img` 中：
 - `public/assets/img/logo.svg` - 用于站点图标、应用图标
 - `public/assets/img/logo.png` - 用于 Open Graph
 - `public/assets/img/avatar_default.png` - 用作默认头像图片
 - `public/assets/img/apple-touch-icon.png` - 用于 iOS 设备书签
 - `public/assets/img/favicon.svg` - 用于 favicon
 - `public/assets/img/favicon.png` - 用作不支持 SVG favicon 的浏览器回退图标
 如果源图片不是矢量格式，您可以尝试使用诸如[这个工具](https://www.aconvert.com/image/png-to-svg/)
 将光栅图像转换为矢量图。
 ## 自定义 Gitea 页面和资源
 Gitea 可执行文件内置了运行所需的全部资源：模板、图片、样式表和翻译。您可以在 `custom`
 目录下放置与原路径一致的替换文件来覆盖其中任意资源。例如，要替换 C++ 仓库默认提供的
 `.gitignore`，我们需要替换 `options/gitignore/C++`。为此，您必须将替换文件放到
 `$GITEA_CUSTOM/options/gitignore/C++`（`CustomPath` 目录位置见本文开头说明）。
 Gitea 的每一个页面都可以修改。动态内容通过 [go template](https://pkg.go.dev/html/template)
 生成，您可以通过在 `$GITEA_CUSTOM/templates` 目录下放置替换文件进行修改。
 要获取任意内嵌文件（包括模板），可以使用[`gitea embedded` 工具](../administration/cmd-embedded.md)。
 另外，也可以在 Gitea 源码仓库的 [`templates`](https://github.com/go-gitea/gitea/tree/main/templates)
 目录中找到它们。（注意：示例链接指向 `main` 分支，请确保所使用的模板与您当前的发布版本兼容。）
 请注意，任何包含在 `{{` 和 `}}` 中的语句都是 Gitea 的模板语法，
 如果您没有完全理解这些组件，就不应修改它们。
 ### 自定义首页 / 主页
 将与您所使用 Gitea 版本对应的 [`home.tmpl`](https://github.com/go-gitea/gitea/blob/main/templates/home.tmpl)
 从 `templates` 目录复制到 `$GITEA_CUSTOM/templates`。
 随后按您的需要编辑即可。
 不要忘记重启 Gitea 以应用更改。
 ### 添加链接和页签
 如果您只是想为顶部导航栏或页脚添加额外链接，或者为仓库视图添加额外页签，
 可以将它们分别放入 `$GITEA_CUSTOM/templates/custom/` 目录中的
 `extra_links.tmpl`（添加到导航栏的链接）、`extra_links_footer.tmpl`
 （添加到页脚左侧的链接）和 `extra_tabs.tmpl`。
 例如，假设您在德国，需要添加法律上通常要求提供的 “Impressum”/关于页面，用来说明谁对站点内容负责：
 只需将该页面放到 `$GITEA_CUSTOM/public/assets/` 目录中
 （例如 `$GITEA_CUSTOM/public/assets/impressum.html`），再在
 `$GITEA_CUSTOM/templates/custom/extra_links.tmpl` 或
 `$GITEA_CUSTOM/templates/custom/extra_links_footer.tmpl` 中加入指向它的链接即可。
 为了匹配当前样式，该链接应使用类名 `item`，并且您可以使用 `{{AppSubUrl}}` 获取基础 URL：
 `<a class="item" href="{{AppSubUrl}}/assets/impressum.html">Impressum</a>`
 更多信息请参见[添加法律页面](../administration/adding-legal-pages.md)。
 您也可以用同样的方式添加新页签，将其放入 `extra_tabs.tmpl` 中。
 与其他页签样式匹配所需的精确 HTML 位于文件 `templates/repo/header.tmpl`
 （[GitHub 源码](https://github.com/go-gitea/gitea/blob/main/templates/repo/header.tmpl)）。
 ### 页面中的其他插入内容
 除了 `extra_links.tmpl` 和 `extra_tabs.tmpl` 之外，您还可以在
 `$GITEA_CUSTOM/templates/custom/` 目录中放置其他有用的模板：
 - `header.tmpl`，位于 `<head>` 结束标签之前，例如可用于添加自定义 CSS 文件。
 - `body_outer_pre.tmpl`，位于 `<body>` 起始标签之后。
 - `body_inner_pre.tmpl`，位于顶部导航栏之前，但已处于主容器 `<div class="full height">` 内部。
 - `body_inner_post.tmpl`，位于主容器结束之前。
 - `body_outer_post.tmpl`，位于底部 `<footer>` 元素之前。
 - `footer.tmpl`，位于 `<body>` 结束标签之前，是放置额外 JavaScript 的合适位置。
 ### 使用 Gitea 变量
 您可以在自定义模板中使用各种 Gitea 变量。
 首先，_临时_ 启用开发模式：在 `app.ini` 中将 `RUN_MODE = prod` 改为 `RUN_MODE = dev`。
 然后在任意模板中添加 `{{ $ | DumpVar }}`，重启 Gitea 并刷新对应页面；
 这样会输出所有可用变量。
 找到所需数据后，使用对应变量即可；例如，如果您需要仓库名称，可以使用 `{{.Repository.Name}}`。
 如果您需要对这些数据做一些转换，而您又不熟悉 Go，一种简单的变通办法是先将数据放入 DOM，
 再添加一小段 JavaScript 脚本来处理它。
 ### 示例：PlantUML
 您可以通过 PlantUML 服务器为 Gitea 的 Markdown 添加 [PlantUML](https://plantuml.com/) 支持。
 数据会被编码后发送到 PlantUML 服务器，再由服务器生成图片。官方在
 http://www.plantuml.com/plantuml 提供了一个在线演示服务器，但如果您（或您的用户）拥有敏感数据，
 则可以改为自建一个 [PlantUML 服务器](https://plantuml.com/server)。要启用 PlantUML 渲染，
 请从 https://gitea.com/davidsvantesson/plantuml-code-highlight 复制 JavaScript 文件，
 并将其放入 `$GITEA_CUSTOM/public/assets/` 目录。然后将以下内容添加到 `$GITEA_CUSTOM/templates/custom/footer.tmpl`：
 ```html
 <script>
  $(async () => {
    if (!$('.language-plantuml').length) return;
    await Promise.all([
      $.getScript('https://your-gitea-server.com/assets/deflate.js'),
      $.getScript('https://your-gitea-server.com/assets/encode.js'),
      $.getScript('https://your-gitea-server.com/assets/plantuml_codeblock_parse.js'),
    ]);
    // Replace call with address to your plantuml server
    parsePlantumlCodeBlocks("https://www.plantuml.com/plantuml");
  });
 </script>
 ```
 随后，您就可以在 Markdown 中添加如下代码块：
 ```plantuml
 Alice -> Bob: Authentication Request
 Bob --> Alice: Authentication Response
 Alice -> Bob: Another authentication Request
 Alice <-- Bob: Another authentication Response
 ```
 该脚本会检测 `class="language-plantuml"` 的标签，不过您也可以通过为
 `parsePlantumlCodeBlocks` 提供第二个参数来修改这一行为。
 ### 示例：使用 Online 3D Viewer 预览 CAD 文件
 您可以在自己的 Gitea 实例中实现 CAD 文件预览。这个实现使用的是
 [`Online 3D Viewer`](https://github.com/kovacsv/Online3DViewer)。
 支持以下 3D 文件格式：
 `3dm`, `3ds`, `3mf`, `amf`, `bim`, `brep`, `dae`, `fbx`, `fcstd`, `glb`,
 `gltf`, `ifc`, `igs`, `iges`, `stp`, `step`, `stl`, `obj`, `off`, `ply`, `wrl`
 （`.gltf` 文件仅支持 v2）
 #### 第 1 部分：添加模板
 我们需要在 `$GITEA_CUSTOM` 中添加模板。
 该模板需要保存到 `$GITEA_CUSTOM/templates/custom/` 中。
 在这里创建 `footer.tmpl` 文件，并向其中添加以下内容：
 ```
 nano $GITEA_CUSTOM/templates/custom/footer.tmpl
 ```
 ```html
 <script>
    function onPageChange() {
      // Supported 3D file types
      const fileTypes = ['3dm', '3ds', '3mf', 'amf', 'bim', 'brep', 'dae', 'fbx', 'fcstd', 'glb', 'gltf', 'ifc', 'igs', 'iges', 'stp', 'step', 'stl', 'obj', 'off', 'ply', 'wrl'];
      // Select matching link
      const links = Array.from(document.querySelectorAll('a.ui.mini.basic.button'));
      const link3D = links.find(link => {
        const href = link.href.toLowerCase();
        return href.includes('/raw/') && fileTypes.some(ext => href.endsWith(`.${ext}`));
      });
 	if (link3D) {
 	  const existingScript = document.querySelector('script[src="/assets/o3dv/o3dv.min.js"]');
 	  const initializeViewer = () => {
 		const fileUrl = link3D.getAttribute('href');
                const fileView = document.querySelector('.file-view');
 		if (!fileView) return;
 		// Remove only the old viewer container if it exists
 		const oldView3D = document.getElementById('view-3d');
 		if (oldView3D) {
 		  oldView3D.remove();  // safely remove old viewer container div
 		} else {
 		  // No #view-3d, so remove all children inside .file-view
 		  while (fileView.firstChild) {
 		    fileView.removeChild(fileView.firstChild);
 		  }
 		}
 		// Create a new container for the viewer
 		const newView3D = document.createElement('div');
 		  newView3D.id = 'view-3d';
 		  newView3D.style.padding = '0';
 		  newView3D.style.margin = '0';
 		  newView3D.style.flexGrow = '1';
 		  newView3D.style.minHeight = '0';
 		  newView3D.style.width = '100%';
 		const header = document.querySelector('header');
 		const headerHeight = header ? header.offsetHeight : 0;
 		newView3D.style.height = `calc(100vh - ${headerHeight}px)`;		
 		// Append the new container inside fileView
 		fileView.appendChild(newView3D);
 		const parentDiv = document.getElementById('view-3d');
 		if (parentDiv) {
 		  const viewer = new OV.EmbeddedViewer(parentDiv, {
 			backgroundColor: new OV.RGBAColor(59, 68, 76, 0),
 			defaultColor: new OV.RGBColor(200, 200, 200),
 			edgeSettings: new OV.EdgeSettings(false, new OV.RGBColor(0, 0, 0), 1),
 			environmentSettings: new OV.EnvironmentSettings([
 			  '/assets/o3dv/envmaps/fishermans_bastion/negx.jpg',
 			  '/assets/o3dv/envmaps/fishermans_bastion/posx.jpg',
 			  '/assets/o3dv/envmaps/fishermans_bastion/posy.jpg',
 			  '/assets/o3dv/envmaps/fishermans_bastion/negy.jpg',
 			  '/assets/o3dv/envmaps/fishermans_bastion/posz.jpg',
 			  '/assets/o3dv/envmaps/fishermans_bastion/negz.jpg'
 			], false)
 		  });
 		  viewer.LoadModelFromUrlList([fileUrl]);
 		}
 	  };
 	  if (typeof OV === 'undefined') {
 		if (!existingScript) {
 		  const script = document.createElement('script');
 		  script.onload = initializeViewer;
 		  script.src = '/assets/o3dv/o3dv.min.js';
 		  document.head.appendChild(script);
 		} else {
 		  // Script is loading but OV not yet ready — wait for it
 		  existingScript.addEventListener('load', initializeViewer);
 		}
 	  } else {
 		// OV already loaded
 		initializeViewer();
 	  }
 	}
    };
    // Run when the page is fully loaded
    document.addEventListener('DOMContentLoaded', onPageChange); 
    const targetSelector = 'a.ui.mini.basic.button[href*="/raw/"]';
    let lastHref = null;
    let timeoutId = null;
    const checkAndRun = () => {
      const rawLink = document.querySelector(targetSelector);
      if (!rawLink) return;
      const currentHref = rawLink.getAttribute('href');
      if (currentHref !== lastHref) {
        lastHref = currentHref;
        const fileName = currentHref.split('/').pop();
        console.log('New Raw file link detected after delay:', fileName);
        onPageChange();
      }
    };
    const observer = new MutationObserver(() => {
      // Delay execution by 300ms after last mutation
      clearTimeout(timeoutId);
      timeoutId = setTimeout(checkAndRun, 300);
    });
    observer.observe(document.body, {
      childList: true,
      subtree: true,
    });
 </script>
 ```
 #### 第 2 部分：添加公共文件
 现在我们需要下载最新版本的 O3DV。进入 `$GITEA_CUSTOM/public/assets/`。
 使用以下命令创建目录（并进入该目录）：
 ```
 mkdir o3dv
 cd o3dv
 ```
 从 [`GitHub`](https://github.com/kovacsv/Online3DViewer/releases) 复制最新发行版压缩包链接
 （当前示例版本为 v0.18.0）。
 然后使用例如 wget 或 curl 下载该文件：
 ```
 wget https://github.com/kovacsv/Online3DViewer/releases/download/0.18.0/o3dv.zip
 ```
 或者
 ```
 curl -L -O https://github.com/kovacsv/Online3DViewer/releases/download/0.18.0/o3dv.zip
 ```
 再使用例如 unzip 解压归档文件：
 ```
 unzip o3dv.zip
 ```
 #### 第 3 部分：目录权限
 最后一步，修改 public 目录权限：
 ```
 chown -R git:git $GITEA_CUSTOM/public
 ```
 现在一切就绪！重启您的 Gitea 实例以应用这些更改，并在浏览器中进行测试。
 简单检查一下。最终目录结构应类似如下：
 ```
 $GITEA_CUSTOM/templates
 -- custom
    `-- footer.tmpl
 $GITEA_CUSTOM/public/assets/
 -- o3dv
   |-- o3dv.zip
   |-- o3dv.license.md
   |-- o3dv.min.js
   |-- envmaps
    \...
 ```
 ## 自定义 Gitea 邮件
 `$GITEA_CUSTOM/templates/mail` 目录允许您修改 Gitea 每一种邮件的正文。
 可被覆盖的模板可以在 Gitea 源码的
 [`templates/mail`](https://github.com/go-gitea/gitea/tree/main/templates/mail)
 目录中找到。
 覆盖方式是将对应文件复制到 `$GITEA_CUSTOM/templates/mail` 下，
 并保持与源码一致的完整路径结构。
 任何包含在 `{{` 和 `}}` 中的语句都是 Gitea 的模板语法，
 如果您没有完全理解这些组件，就不应修改它们。
 ## 为 Gitea 添加统计分析
 Google Analytics、Matomo（原 Piwik）以及其他分析服务都可以集成到 Gitea。
 要添加跟踪代码，请参考本文的“页面中的其他插入内容”一节，
 并将相应 JavaScript 添加到 `$GITEA_CUSTOM/templates/custom/header.tmpl` 文件中。
 ## 自定义 gitignores、labels、licenses、locales 和 readmes
 将自定义文件放入 `custom/options` 下对应的子目录中。
 :::note
 这些文件不应带有扩展名，例如应使用 `Labels`，而不是 `Labels.txt`
 :::
 ### gitignores
 要添加自定义 `.gitignore`，请在 `$GITEA_CUSTOM/options/gitignore` 中添加一个文件，
 文件内容遵循现有的 [.gitignore 规则](https://git-scm.com/docs/gitignore)。
 ## 自定义 git 配置
 从 Gitea 1.20 开始，您可以通过 `git.config` 区块自定义 git 配置。
 ### 启用签名 git push
 [签名推送](https://git-scm.com/docs/git-push#Documentation/git-push.txt---signedtruefalseif-asked)
 允许客户端对 push 操作本身进行加密签名（而不仅仅是对单个提交签名）。
 要启用签名推送，请将以下内容添加到 `app.ini`：
 ```ini
 [git.config]
 receive.certNonceSeed = <randomstring>
 ```
 `certNonceSeed` 应设置为一个随机字符串并妥善保密。它用于生成防重放 nonce。
 Gitea 默认已经设置了 `receive.advertisePushOptions = true`，因此无需额外配置。
 请注意，Gitea 不会读取 `/etc/gitconfig`，因此必须像上面这样通过 `app.ini` 设置该选项。
 在客户端侧，可以通过 `git push --signed` 进行签名推送，
 或者使用 `git config --global push.gpgSign if-asked` 永久启用。
 ### Labels
 从 Gitea 1.19 开始，您可以向 `$GITEA_CUSTOM/options/label` 中添加一个遵循
 [YAML 标签格式](https://github.com/go-gitea/gitea/blob/main/options/label/Advanced.yaml)
 的文件：
 ```yaml
 labels:
  - name: "foo/bar"  # 下拉列表中显示的标签名称
    exclusive: true # 是否为作用域标签使用互斥命名空间，作用域分隔符为 /
    color: aabbcc # 十六进制颜色值
    description: Some label # 标签用途的详细描述
 ```
 旧的[传统文件格式](https://github.com/go-gitea/gitea/blob/main/options/label/Default)
 仍可使用，格式如下，但我们强烈建议改用新的 YAML 格式。
 `#hex-color label name ; label description`
 更多信息请参阅[标签文档](../usage/issues-prs/labels.md)。
 ### Licenses
 要添加自定义许可证，请将包含许可证文本的文件添加到 `$GITEA_CUSTOM/options/license`。
 ### Locales
 本地化语言由我们的 [Crowdin](https://crowdin.com/project/gitea) 管理。
 您可以通过将修改后的语言文件放到 `$GITEA_CUSTOM/options/locale` 中来覆盖某个语言环境。
 Gitea 默认的语言文件可以在源码目录
 [`options/locale`](https://github.com/go-gitea/gitea/tree/main/options/locale) 中找到，
 这些文件可以作为您修改时的参考示例。
 如果要添加一个全新的语言环境，除了将文件放到上述位置外，
 您还需要在 `app.ini` 的 `[i18n]` 部分中添加新的语言代码和名称。
 请记住，Gitea 会将这些设置视为**覆盖项**，因此如果您还想保留其他语言，
 就需要复制默认值并在其中加入您自己的语言项。
 ```ini title="app.ini"
 [i18n]
 LANGS = en-US,foo-BAR
 NAMES = English,FooBar
 ```
 如果用户浏览器的语言与列表中的任何语言都不匹配，则第一种语言会被用作默认语言。
 不同版本之间的语言文件可能会变化，因此强烈建议持续跟踪您自定义过的语言文件。
 ### Readmes
 要添加自定义 Readme，请将一个 Markdown 格式的文件（不带 `.md` 扩展名）
 放到 `$GITEA_CUSTOM/options/readme` 中。
 :::note
 Readme 模板支持**变量展开**。
 当前可用变量包括 `{Name}`（仓库名称）、`{Description}`、`{CloneURL.SSH}`、`{CloneURL.HTTPS}` 和 `{OwnerName}`
 :::
 ### Reactions
 要修改反应表情，您可以在 `app.ini` 中设置允许使用的 reactions。
 ```ini title="app.ini"
 [ui]
 REACTIONS = +1, -1, laugh, confused, heart, hooray, eyes
 ```
 完整的受支持 emoji 列表见 [emoji list](https://gitea.com/gitea/gitea.com/issues/8)。
 ## 自定义 Gitea 外观
 内置主题有 `gitea-light`、`gitea-dark` 和 `gitea-auto`
 （会自动适应操作系统设置）。
 默认主题可以通过 `app.ini` 中 [ui](../administration/config-cheat-sheet.md#界面) 部分的
 `DEFAULT_THEME` 进行修改。
 Gitea 还支持用户主题，这意味着每位用户都可以选择要使用的主题。
 用户可选主题列表可以通过 `app.ini` 中 [ui](../administration/config-cheat-sheet.md#界面)
 部分的 `THEMES` 值进行配置。
 要让所有用户都能使用自定义主题：
 1. 将 CSS 文件添加到 `$GITEA_CUSTOM/public/assets/css/theme-<theme-name>.css`。
   您可以通过执行 `gitea help` 并查看其中的 “CustomPath” 值来确认实例的 `$GITEA_CUSTOM`。
 2. 将 `<theme-name>` 添加到 `app.ini` 中 `THEMES` 设置的逗号分隔列表中，
   或者将 `THEMES` 留空以允许所有主题。
 名为 `theme-my-theme.css` 的自定义主题文件会在用户主题选择页面中显示为 `my-theme`。
 您还可以在自定义主题 CSS 文件中加入主题元信息，以提供更多说明。
 如果自定义主题是暗色主题，请在 `:root` 块中设置全局 CSS 变量 `--is-dark-theme: true`。
 这样 Gitea 就可以相应地调整 Monaco 代码编辑器的主题。
 如果要实现 “auto” 主题，可以参考 `theme-gitea-auto.css`。
 ```css
 gitea-theme-meta-info {
  --theme-display-name: "My Awesome Theme"; /* this theme will be display as "My Awesome Theme" on the UI */
 }
 :root {
  --is-dark-theme: true; /* if it is a dark theme */
  --color-primary: #112233;
  /* more custom theme variables ... */
 }
 ```
 社区主题列在 [gitea/awesome-gitea#themes](https://gitea.com/gitea/awesome-gitea#themes)。
 默认主题源码可在[这里](https://github.com/go-gitea/gitea/blob/main/web_src/css/themes)找到。
 ## 自定义字体
 可以使用 CSS 变量自定义字体：
 ```css
 :root {
  --fonts-proportional: /* custom proportional fonts */ !important;
  --fonts-monospace: /* custom monospace fonts */ !important;
  --fonts-emoji: /* custom emoji fonts */ !important;
 }
 ```
@@ -1,77 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 slug: "email-setup"
 sidebar_position: 12
 aliases:
  - /zh-cn/email-setup
 ---
 # Email 设置
 Gitea 具有邮件功能，用于发送事务性邮件（例如注册确认邮件）。它可以配置为使用 Sendmail（或兼容的 MTA，例如 Postfix 和 msmtp）或直接使用 SMTP 服务器。
 ## 使用 Sendmail
 使用 `sendmail` 命令作为邮件传输代理（mailer）。
 注意：对于在官方 Gitea Docker 镜像中使用，请使用 SMTP 版本进行配置（请参考下一节）。
 注意：对于面向互联网的网站，请查阅您的 MTA 文档以了解通过 TLS 发送邮件的说明。同时设置 SPF、DMARC 和 DKIM DNS 记录，以使发送的邮件被各个电子邮件提供商接受为合法邮件。
 ```ini title="app.ini"
 [mailer]
 ENABLED       = true
 FROM          = gitea@mydomain.com
 PROTOCOL   = sendmail
 SENDMAIL_PATH = /usr/sbin/sendmail
 SENDMAIL_ARGS = "--" ; 大多数 "sendmail" 程序都接受选项，使用 "--" 将防止电子邮件地址被解释为选项。
 ```
 ## 使用 SMTP
 直接使用 SMTP 服务器作为中继。如果您不想在实例上设置 MTA，但在电子邮件提供商那里有一个帐户，这个选项非常有用。
 ```ini title="app.ini"
 [mailer]
 ENABLED        = true
 FROM           = gitea@mydomain.com
 PROTOCOL    = smtps
 SMTP_ADDR      = mail.mydomain.com
 SMTP_PORT      = 587
 USER           = gitea@mydomain.com
 PASSWD         = `password`
 ```
 重启 Gitea 以使配置更改生效。
 要发送测试邮件以验证设置，请转到 Gitea > 站点管理 > 配置 > SMTP 邮件配置。
 有关所有选项的完整列表，请查看[配置速查表](../administration/config-cheat-sheet.md)。
 请注意：只有在使用 TLS 或 `HOST=localhost` 加密 SMTP 服务器通信时才支持身份验证。TLS 加密可以通过以下方式进行：
 - 通过端口 587 的 STARTTLS（也称为 Opportunistic TLS）。初始连接是明文的，但如果服务器支持，则可以升级为 TLS。
 - 通过默认端口 465 的 SMTPS 连接。连接到服务器从一开始就使用 TLS。
 - 使用 `PROTOCOL=smtps` 进行强制的 SMTPS 连接。（这两种方式都被称为 Implicit TLS）
  这是由于 Go 内部库对 STRIPTLS 攻击的保护机制。
 请注意，自 2018 年起，[RFC8314](https://tools.ietf.org/html/rfc8314#section-3) 推荐使用 Implicit TLS。
 ### Gmail
 以下配置应该适用于 Gmail 的 SMTP 服务器：
 ```ini title="app.ini"
 [mailer]
 ENABLED        = true
 HOST           = smtp.gmail.com:465 ; 对于 Gitea >= 1.18.0，删除此行
 SMTP_ADDR      = smtp.gmail.com
 SMTP_PORT      = 465
 FROM           = example.user@gmail.com
 USER           = example.user
 PASSWD         = `***`
 PROTOCOL    = smtps
 ```
 请注意，您需要创建并使用一个 [应用密码](https://support.google.com/accounts/answer/185833?hl=en) 并在您的 Google 帐户上启用 2FA。您将无法直接使用您的 Google 帐户密码。
@@ -1,49 +0,0 @@
 ---
 date: "2017-04-08T11:34:00+02:00"
 slug: "environment-variables"
 sidebar_position: 10
 aliases:
  - /zh-cn/environment-variables
 ---
 # 环境变量清单
 这里是用来控制 Gitea 行为表现的的环境变量清单，您需要在执行如下 Gitea 启动命令前设置它们来确保配置生效：
 ```
 GITEA_CUSTOM=/home/gitea/custom ./gitea web
 ```
 ## Go 的配置
 因为 Gitea 使用 Go 语言编写，因此它使用了一些相关的 Go 的配置参数：
 - `GOOS`
 - `GOARCH`
 - [`GOPATH`](https://go.dev/cmd/go/#hdr-GOPATH_environment_variable)
 您可以在[官方文档](https://go.dev/cmd/go/#hdr-Environment_variables)中查阅这些配置参数的详细信息。
 ## Gitea 的文件目录
 - `GITEA_WORK_DIR`：工作目录的绝对路径
 - `GITEA_CUSTOM`：默认情况下 Gitea 使用默认目录 `GITEA_WORK_DIR`/custom，您可以使用这个参数来配置 _custom_ 目录
 - `GOGS_WORK_DIR`： 已废弃，请使用 `GITEA_WORK_DIR` 替代
 - `GOGS_CUSTOM`： 已废弃，请使用 `GITEA_CUSTOM` 替代
 ## 操作系统配置
 - `USER`：Gitea 运行时使用的系统用户，它将作为一些 repository 的访问地址的一部分
 - `USERNAME`： 如果没有配置 `USER`， Gitea 将使用 `USERNAME`
 - `HOME`： 用户的 home 目录，在 Windows 中会使用 `USERPROFILE` 环境变量
 ### 仅限于 Windows 的配置
 - `USERPROFILE`： 用户的主目录，如果未配置则会使用 `HOMEDRIVE` + `HOMEPATH`
 - `HOMEDRIVE`: 用于访问 home 目录的主驱动器路径（C 盘）
 - `HOMEPATH`：在指定主驱动器下的 home 目录相对路径
 ## Miscellaneous
 - `SKIP_MINWINSVC`：如果设置为 1，在 Windows 上不会以 service 的形式运行。
@@ -1,194 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 slug: "external-renderers"
 sidebar_position: 60
 aliases:
  - /zh-cn/external-renderers
 ---
 # 外部渲染器
 Gitea 通过外部二进制文件支持自定义文件渲染（例如 Jupyter notebooks、asciidoc 等），只需要进行以下步骤：
 - 安装外部二进制文件
 - 在您的 `app.ini` 文件中添加一些配置
 - 重新启动 Gitea 实例
 此功能支持整个文件的渲染。如果您想要在 Markdown 中渲染代码块，您需要使用 JavaScript 进行一些操作。请参阅 [自定义 Gitea 配置](../administration/customizing-gitea.md) 页面上的一些示例。
 ## 安装外部二进制文件
 为了通过外部二进制文件进行文件渲染，必须安装它们的关联软件包。
 如果您正在使用 Docker 镜像，则您的 `Dockerfile` 应该包含以下内容：
 ```docker
 FROM docker.gitea.com/gitea:@dockerVersion@
 [...]
 COPY custom/app.ini /data/gitea/conf/app.ini
 [...]
 RUN apk --no-cache add asciidoctor freetype freetype-dev gcc g++ libpng libffi-dev pandoc python3-dev py3-pyzmq pipx
 # 安装其他您需要的外部渲染器的软件包
 RUN pipx install jupyter docutils --include-deps
 # 在上面添加您需要安装的任何其他 Python 软件包
 ```
 ## `app.ini` 文件配置
 在您的自定义 `app.ini` 文件中为每个外部渲染器添加一个 `[markup.XXXXX]` 部分：
 ```ini
 [markup.asciidoc]
 ENABLED = true
 FILE_EXTENSIONS = .adoc,.asciidoc
 RENDER_COMMAND = "asciidoctor -s -a showtitle --out-file=- -"
 ; 输入不是标准输入而是文件
 IS_INPUT_FILE = false
 [markup.jupyter]
 ENABLED = true
 FILE_EXTENSIONS = .ipynb
 RENDER_COMMAND = "jupyter nbconvert --stdin --stdout --to html --template basic"
 IS_INPUT_FILE = false
 [markup.restructuredtext]
 ENABLED = true
 FILE_EXTENSIONS = .rst
 RENDER_COMMAND = "timeout 30s pandoc +RTS -M512M -RTS -f rst"
 IS_INPUT_FILE = false
 ```
 如果您的外部标记语言依赖于在生成的 HTML 元素上的额外类和属性，您可能需要启用自定义的清理策略。Gitea 使用 [`bluemonday`](https://godoc.org/github.com/microcosm-cc/bluemonday) 包作为我们的 HTML 清理器。下面的示例可以用于支持从 [`pandoc`](https://pandoc.org/) 输出的服务器端 [KaTeX](https://katex.org/) 渲染结果。
 ```ini
 [markup.sanitizer.TeX]
 ; Pandoc 渲染 TeX 段落为带有 "math" 类的 <span> 元素，根据上下文可能还带有 "inline" 或 "display" 类。
 ; - 请注意，这与我们的 Markdown 解析器中内置的数学支持不同，后者使用 <code> 元素。
 ELEMENT = span
 ALLOW_ATTR = class
 REGEXP = ^\s*((math(\s+|$)|inline(\s+|$)|display(\s+|$)))+
 [markup.markdown]
 ENABLED         = true
 FILE_EXTENSIONS = .md,.markdown
 RENDER_COMMAND  = pandoc -f markdown -t html --katex
 ```
 您必须在每个部分中定义 `ELEMENT` 和 `ALLOW_ATTR`。
 要定义多个条目，请添加唯一的字母数字后缀（例如，`[markup.sanitizer.1]` 和 `[markup.sanitizer.something]`）。
 要仅为特定的外部渲染器应用清理规则，它们必须使用渲染器名称，例如 `[markup.sanitizer.asciidoc.rule-1]`、`[markup.sanitizer.<renderer>.rule-1]`。
 **注意**：如果规则在渲染器 ini 部分之前定义，或者名称与渲染器不匹配，它将应用于所有渲染器。
 完成配置更改后，请重新启动 Gitea 以使更改生效。
 **注意**：在 Gitea 1.12 之前，存在一个名为 `markup.sanitiser` 的单个部分，其中的键被重新定义为多个规则，但是，这种配置方法存在重大问题，需要通过多个部分进行配置。
 ### 示例：HTML
 直接渲染 HTML 文件：
 ```ini
 [markup.html]
 ENABLED         = true
 FILE_EXTENSIONS = .html,.htm
 RENDER_COMMAND  = cat
 ; 输入不是标准输入，而是文件
 IS_INPUT_FILE   = true
 [markup.sanitizer.html.1]
 ELEMENT = div
 ALLOW_ATTR = class
 [markup.sanitizer.html.2]
 ELEMENT = a
 ALLOW_ATTR = class
 ```
 请注意：此示例中的配置将允许渲染 HTML 文件，并使用 `cat` 命令将文件内容输出为 HTML。此外，配置中的两个清理规则将允许 `<div>` 和 `<a>` 元素使用 `class` 属性。
 在进行配置更改后，请重新启动 Gitea 以使更改生效。
 ### 示例：Office DOCX
 使用 [`pandoc`](https://pandoc.org/) 显示 Office DOCX 文件：
 ```ini
 [markup.docx]
 ENABLED = true
 FILE_EXTENSIONS = .docx
 RENDER_COMMAND = "pandoc --from docx --to html --self-contained --template /path/to/basic.html"
 [markup.sanitizer.docx.img]
 ALLOW_DATA_URI_IMAGES = true
 ```
 在此示例中，配置将允许显示 Office DOCX 文件，并使用 `pandoc` 命令将文件转换为 HTML 格式。同时，清理规则中的 `ALLOW_DATA_URI_IMAGES` 设置为 `true`，允许使用 Data URI 格式的图片。
 模板文件的内容如下：
 ```
 $body$
 ```
 ### 示例：Jupyter Notebook
 使用 [`nbconvert`](https://github.com/jupyter/nbconvert) 显示 Jupyter Notebook 文件：
 ```ini
 [markup.jupyter]
 ENABLED = true
 FILE_EXTENSIONS = .ipynb
 RENDER_COMMAND = "jupyter-nbconvert --stdin --stdout --to html --template basic"
 [markup.sanitizer.jupyter.img]
 ALLOW_DATA_URI_IMAGES = true
 ```
 在此示例中，配置将允许显示 Jupyter Notebook 文件，并使用 `nbconvert` 命令将文件转换为 HTML 格式。同样，清理规则中的 `ALLOW_DATA_URI_IMAGES` 设置为 `true`，允许使用 Data URI 格式的图片。
 在进行配置更改后，请重新启动 Gitea 以使更改生效。
 ## 自定义 CSS
 在 `.ini` 文件中，可以使用 `[markup.XXXXX]` 的格式指定外部渲染器，并且由外部渲染器生成的 HTML 将被包装在一个带有 `markup` 和 `XXXXX` 类的 `<div>` 中。`markup` 类提供了预定义的样式（如果 `XXXXX` 是 `markdown`，则使用 `markdown` 类）。否则，您可以使用这些类来针对渲染的 HTML 内容进行定制样式。
 因此，您可以编写一些 CSS 样式：
 ```css
 .markup.XXXXX html {
  font-size: 100%;
  overflow-y: scroll;
  -webkit-text-size-adjust: 100%;
  -ms-text-size-adjust: 100%;
 }
 .markup.XXXXX body {
  color: #444;
  font-family: Georgia, Palatino, "Palatino Linotype", Times, "Times New Roman",
    serif;
  font-size: 12px;
  line-height: 1.7;
  padding: 1em;
  margin: auto;
  max-width: 42em;
  background: #fefefe;
 }
 .markup.XXXXX p {
  color: orangered;
 }
 ```
 将您的样式表添加到自定义目录中，例如 `custom/public/assets/css/my-style-XXXXX.css`，并使用自定义的头文件 `custom/templates/custom/header.tmpl` 进行导入：
 ```html
 <link rel="stylesheet" href="{{AppSubUrl}}/assets/css/my-style-XXXXX.css" />
 ```
 通过以上步骤，您可以将自定义的 CSS 样式应用到特定的外部渲染器，使其具有所需的样式效果。
@@ -1,86 +0,0 @@
 ---
 date: "2022-08-01T00:00:00+00:00"
 slug: "fail2ban-setup"
 sidebar_position: 16
 aliases:
  - /zh-cn/fail2ban-setup
 ---
 # 设置 Fail2ban
 **Fail2ban 检查客户端登录日志，将多次登录失败的客户端识别为攻击者并在一段时间内阻止其访问服务。如果你的实例是公开的，这一点尤其重要。请管理员仔细设置 fail2ban，错误的配置将导致防火墙阻止你访问自己的服务器。**
 Gitea 会在日志文件 `log/gitea.log` 中记录登录失败的 CLI、SSH 或 HTTP 客户端 IP 地址，而你需要将 Gitea 的日志输出模式从默认的 `console` 更改为 `file`。这表示将日志输出到文件，使得 fail2ban 可以定期扫描日志内容。
 当用户的身份验证失败时，日志中会记录此类信息：
 ```log
 2018/04/26 18:15:54 [I] Failed authentication attempt for user from xxx.xxx.xxx.xxx
 ```
 ```log
 2020/10/15 16:08:44 [E] invalid credentials from xxx.xxx.xxx.xxx
 ```
 ## 配置规则
 添加日志过滤器规则到配置文件 `/etc/fail2ban/filter.d/gitea.conf`:
 ```ini
 [Definition]
 failregex =  .*(Failed authentication attempt|invalid credentials|Attempted access of unknown user).* from <HOST>
 ignoreregex =
 ```
 添加监狱规则到配置文件 `/etc/fail2ban/jail.d/gitea.conf`:
 ```ini
 [gitea]
 enabled = true
 filter = gitea
 logpath = /var/lib/gitea/log/gitea.log
 maxretry = 10
 findtime = 3600
 bantime = 900
 action = iptables-allports
 ```
 如果你的 Gitea 实例运行在 Docker 容器中，并且直接将容器端口暴露到外部网络，
 你还需要添加 `chain="FORWARD"` 到监狱规则配置文件 `/etc/fail2ban/jail.d/gitea-docker.conf`
 以适应 Docker 的网络转发规则。但如果你在容器的宿主机上使用 Nginx 反向代理连接到 Gitea 则无需这样配置。
 ```ini
 [gitea-docker]
 enabled = true
 filter = gitea
 logpath = /var/lib/gitea/log/gitea.log
 maxretry = 10
 findtime = 3600
 bantime = 900
 action = iptables-allports[chain="FORWARD"]
 ```
 最后，运行 `systemctl restart fail2ban` 即可应用更改。现在，你可以使用 `systemctl status fail2ban` 检查 fail2ban 运行状态。
 上述规则规定客户端在 1 小时内，如果登录失败的次数达到 10 次，则通过 iptables 锁定该客户端 IP 地址 15 分钟。
 ## 设置反向代理
 如果你使用 Nginx 反向代理到 Gitea 实例，你还需要设置 Nginx 的 HTTP 头部值 `X-Real-IP` 将真实的客户端 IP 地址传递给 Gitea。否则 Gitea 程序会将客户端地址错误解析为反向代理服务器的地址，例如回环地址 `127.0.0.1`。
 ```
 proxy_set_header X-Real-IP $remote_addr;
 ```
 额外注意，在 Gitea 的配置文件 `app.ini` 中存在下列默认值：
 ```
 REVERSE_PROXY_LIMIT = 1
 REVERSE_PROXY_TRUSTED_PROXIES = 127.0.0.0/8,::1/128
 ```
 `REVERSE_PROXY_LIMIT` 限制反向代理服务器的层数，设置为 `0` 表示不使用这些标头。
 `REVERSE_PROXY_TRUSTED_PROXIES` 表示受信任的反向代理服务器网络地址，
 经过该网络地址转发来的流量会经过解析 `X-Real-IP` 头部得到真实客户端地址。
 （参考 [configuration cheat sheet](../administration/config-cheat-sheet.md#安全性)）
@@ -1,24 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 slug: "git-lfs-setup"
 sidebar_position: 12
 aliases:
  - /zh-cn/git-lfs-setup
 ---
 # Git LFS 设置
 要使用 Gitea 内置的 LFS 支持，您需要更新 `app.ini` 文件：
 ```ini
 [server]
 ; 启用 git-lfs 支持。true 或 false，默认为 false。
 LFS_START_SERVER = true
 [lfs]
 ; 存放 LFS 文件的路径，默认为 data/lfs。
 PATH = /home/gitea/data/lfs
 ```
 **注意**：LFS 服务器支持需要服务器上安装 Git v2.1.2 以上版本。
@@ -1,89 +0,0 @@
 ---
 date: "2023-04-09T11:00:00+02:00"
 slug: "https-setup"
 sidebar_position: 12
 ---
 # HTTPS配置
 ## 使用内置服务器
 在启用HTTPS之前，确保您拥有有效的SSL/TLS证书。
 建议在测试和评估情况下使用自签名证书，请运行 `gitea cert --host [HOST]` 以生成自签名证书
 如果您在服务器上使用阿帕奇（Apache）或Nginx，建议参考 [反向代理指南](reverse-proxies.md)。
 要使用Gitea内置HTTPS支持，您必须编辑`app.ini`文件。
 ```ini
 [server]
 PROTOCOL  = https
 ROOT_URL  = https://git.example.com:3000/
 HTTP_PORT = 3000
 CERT_FILE = cert.pem
 KEY_FILE  = key.pem
 ```
 请注意，如果您的证书由第三方证书颁发机构签名（即不是自签名的），则 cert.pem 应包含证书链。服务器证书必须是 cert.pem 中的第一个条目，后跟中介（如果有）。不必包含根证书，因为连接客户端必须已经拥有根证书才能建立信任关系。要了解有关配置值的更多信息，请查看 [配置备忘单](../administration/config-cheat-sheet#server-server)。
 对于“CERT_FILE”或“KEY_FILE”字段，当文件路径是相对路径时，文件路径相对于“GITEA_CUSTOM”环境变量。它也可以是绝对路径。
 ### 设置HTTP重定向
 Gitea服务器仅支持监听一个端口；要重定向HTTP请求致HTTPS端口，您需要启用HTTP重定向服务：
 ```ini
 [server]
 REDIRECT_OTHER_PORT = true
 ; Port the redirection service should listen on
 PORT_TO_REDIRECT = 3080
 ```
 如果您使用Docker，确保端口已配置在 `docker-compose.yml` 文件
 ## 使用 ACME (默认: Let's Encrypt)
 [ACME](https://tools.ietf.org/html/rfc8555) 是一种证书颁发机构标准协议，允许您自动请求和续订 SSL/TLS 证书。[Let`s Encrypt](https://letsencrypt.org/) 是使用此标准的免费公开信任的证书颁发机构服务器。仅实施“HTTP-01”和“TLS-ALPN-01”挑战。为了使 ACME 质询通过并验证您的域所有权，“80”端口（“HTTP-01”）或“443”端口（“TLS-ALPN-01”）上 gitea 域的外部流量必须由 gitea 实例提供服务。可能需要设置 [HTTP 重定向](#设置http重定向) 和端口转发才能正确路由外部流量。否则，到端口“80”的正常流量将自动重定向到 HTTPS。**您必须同意**ACME提供商的服务条款（默认为Let's Encrypt的 [服务条款](https://letsencrypt.org/documents/LE-SA-v1.2-2017年11月15日.pdf)。
 使用默认 Let's Encrypt 的最小配置如下：
 ```ini
 [server]
 PROTOCOL=https
 DOMAIN=git.example.com
 ENABLE_ACME=true
 ACME_ACCEPTTOS=true
 ACME_DIRECTORY=https
 ;; Email can be omitted here and provided manually at first run, after which it is cached
 ACME_EMAIL=email@example.com
 ```
 小型配置请使用 [smallstep CA](https://github.com/smallstep/certificates), 点击 [教程](https://smallstep.com/docs/tutorials/acme-challenge) 了解更多信息。
 ```ini
 [server]
 PROTOCOL=https
 DOMAIN=git.example.com
 ENABLE_ACME=true
 ACME_ACCEPTTOS=true
 ACME_URL=https://ca.example.com/acme/acme/directory
 ;; Can be omitted if using the system's trust is preferred
 ;ACME_CA_ROOT=/path/to/root_ca.crt
 ACME_DIRECTORY=https
 ACME_EMAIL=email@example.com
 ```
 要了解关于配置, 请访问 [配置备忘单](../administration/config-cheat-sheet.md#server-server)获取更多信息
 ## 使用反向代理服务器
 按照 [reverse proxy guide](reverse-proxies.md) 的规则设置你的反向代理服务器
 然后，按照下面的向导启用 HTTPS：
 - [nginx](https://nginx.org/en/docs/http/configuring_https_servers.html)
 - [apache2/httpd](https://httpd.apache.org/docs/2.4/ssl/ssl_howto.html)
 - [caddy](https://caddyserver.com/docs/tls)
 注意：仅在代理层启用 HTTPS 被称为 [TLS 终止代理](https://en.wikipedia.org/wiki/TLS_termination_proxy)。代理服务器接受传入的 TLS 连接，解密内容，然后将现在未加密的内容传递给 Gitea。只要代理和 Gitea 实例在同一台计算机上或在私有网络中的不同计算机上（代理暴露给外部网络），这通常是可以接受的。如果您的 Gitea 实例与代理隔离在公共网络上，或者如果您想要全端到端的加密，您还可以直接在 Gitea 中 [启用内置服务器的 HTTPS 支持](#使用内置服务器)，并将连接转发到 HTTPS 上。
@@ -1,263 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 slug: "logging-config"
 sidebar_position: 40
 aliases:
  - /zh-cn/logging-configuration
 ---
 # 日志配置
 Gitea 的日志配置主要由以下三种类型的组件组成：
 - `[log]` 部分用于一般配置
 - `[log.<mode-name>]` 部分用于配置不同的日志输出方式，也称为 "writer mode"，模式名称同时也作为 "writer name"
 - `[log]` 部分还可以包含遵循 `logger.<logger-name>.<CONFIG-KEY>` 模式的子日志记录器的配置
 默认情况下，已经有一个完全功能的日志输出，因此不需要重新定义。
 ## 收集日志以获取帮助
 要收集日志以获取帮助和报告问题，请参阅 [需要帮助](help/support.md)。
 ## `[log]` 部分
 在 Gitea 中，日志设施的配置在 `[log]` 部分及其子部分。
 在顶层的 `[log]` 部分，可以放置以下配置项：
 - `ROOT_PATH`：（默认值：**%(GITEA_WORK_DIR)/log**）：日志文件的基本路径。
 - `MODE`：（默认值：**console**）：要用于默认日志记录器的日志输出列表。
 - `LEVEL`：（默认值：**Info**）：要持久化的最严重的日志事件，不区分大小写。可能的值为：`Trace`、`Debug`、`Info`、`Warn`、`Error`、`Fatal`。
 - `STACKTRACE_LEVEL`：（默认值：**None**）：对于此类及更严重的事件，将在记录时打印堆栈跟踪。
 它还可以包含以下子日志记录器：
 - `logger.router.MODE`：（默认值：**,**）：用于路由器日志记录器的日志输出列表。
 - `logger.access.MODE`：（默认值：**_empty_**）：用于访问日志记录器的日志输出列表。默认情况下，访问日志记录器被禁用。
 - `logger.xorm.MODE`：（默认值：**,**）：用于 XORM 日志记录器的日志输出列表。
 将子日志记录器的模式设置为逗号（`,`）表示使用默认的全局 `MODE`。
 ## 快速示例
 ### 默认（空）配置
 空配置等同于默认配置：
 ```ini
 [log]
 ROOT_PATH = %(GITEA_WORK_DIR)/log
 MODE = console
 LEVEL = Info
 STACKTRACE_LEVEL = None
 logger.router.MODE = ,
 logger.xorm.MODE = ,
 logger.access.MODE =
 ; 这是“控制台”模式的配置选项（由上面的 MODE=console 使用）
 [log.console]
 MODE = console
 FLAGS = stdflags
 PREFIX =
 COLORIZE = true
 ```
 这等同于将所有日志发送到控制台，并将默认的 Golang 日志也发送到控制台日志中。
 这只是一个示例，默认情况下不需要将其写入配置文件中。
 ### 禁用路由日志并将一些访问日志记录到文件中
 禁用路由日志，将访问日志（>=Warn）记录到 `access.log` 中：
 ```ini
 [log]
 logger.router.MODE =
 logger.access.MODE = access-file
 [log.access-file]
 MODE = file
 LEVEL = Warn
 FILE_NAME = access.log
 ```
 ### 为不同的模式设置不同的日志级别
 将默认日志（>=Warn）记录到 `gitea.log` 中，将错误日志记录到 `file-error.log` 中：
 ```ini
 [log]
 LEVEL = Warn
 MODE = file, file-error
 ; 默认情况下，"file" 模式会将日志记录到 %(log.ROOT_PATH)/gitea.log，因此我们不需要设置它
 ; [log.file]
 [log.file-error]
 LEVEL = Error
 FILE_NAME = file-error.log
 ```
 ## 日志输出（模式和写入器）
 Gitea 提供以下日志写入器：
 - `console` - 输出日志到 `stdout`（或 `stderr`，如果已在配置中设置）
 - `file` - 输出日志到文件
 - `conn` - 输出日志到套接字（网络或 Unix 套接字）
 ### 公共配置
 某些配置适用于所有日志输出模式：
 - `MODE` 是日志输出写入器的模式。它将默认为 ini 部分的模式名称。因此，`[log.console]` 将默认为 `MODE = console`。
 - `LEVEL` 是此输出将记录的最低日志级别。
 - `STACKTRACE_LEVEL` 是此输出将打印堆栈跟踪的最低日志级别。
 - `COLORIZE` 对于 `console`，默认为 `true`，否则默认为 `false`。
 #### `EXPRESSION`
 `EXPRESSION` 表示日志事件必须匹配才能被输出写入器记录的正则表达式。
 日志消息（去除颜色）或 `longfilename:linenumber:functionname` 必须匹配其中之一。
 注意：整个消息或字符串不需要完全匹配。
 请注意，此表达式将在写入器的 goroutine 中运行，而不是在日志事件的 goroutine 中运行。
 #### `FLAGS`
 `FLAGS` 表示在每条消息之前打印的前置日志上下文信息。
 它是一个逗号分隔的字符串集。值的顺序无关紧要。
 默认值为 `stdflags`（= `date,time,medfile,shortfuncname,levelinitial`）。
 可能的值为：
 - `none` 或 `,` - 无标志。
 - `date` - 当地时区的日期：`2009/01/23`。
 - `time` - 当地时区的时间：`01:23:23`。
 - `microseconds` - 微秒精度：`01:23:23.123123`。假定有时间。
 - `longfile` - 完整的文件名和行号：`/a/b/c/d.go:23`。
 - `shortfile` - 文件名的最后一个部分和行号：`d.go:23`。
 - `funcname` - 调用者的函数名：`runtime.Caller()`。
 - `shortfuncname` - 函数名的最后一部分。覆盖 `funcname`。
 - `utc` - 如果设置了日期或时间，则使用 UTC 而不是本地时区。
 - `levelinitial` - 提供的级别的初始字符，放在方括号内，例如 `[I]` 表示 info。
 - `level` - 在方括号内的级别，例如 `[INFO]`。
 - `gopid` - 上下文的 Goroutine-PID。
 - `medfile` - 文件名的最后 20 个字符 - 相当于 `shortfile,longfile`。
 - `stdflags` - 相当于 `date,time,medfile,shortfuncname,levelinitial`。
 ### Console 模式
 在此模式下，日志记录器将将日志消息转发到 Gitea 进程附加的 stdout 和 stderr 流。
 对于 console 模式的日志记录器，如果不在 Windows 上，或者 Windows 终端可以设置为 ANSI 模式，或者是 cygwin 或 Msys 管道，则 `COLORIZE` 默认为 `true`。
 设置：
 - `STDERR`：**false**：日志记录器是否应将日志打印到 `stderr` 而不是 `stdout`。
 ### File 模式
 在此模式下，日志记录器将将日志消息保存到文件中。
 设置：
 - `FILE_NAME`：要将日志事件写入的文件，相对于 `ROOT_PATH`，默认为 `%(ROOT_PATH)/gitea.log`。异常情况：访问日志默认为 `%(ROOT_PATH)/access.log`。
 - `MAX_SIZE_SHIFT`：**28**：单个文件的最大大小位移。28 表示 256Mb。详细信息见下文。
 - `LOG_ROTATE` **true**：是否轮转日志文件。
 - `DAILY_ROTATE`：**true**：是否每天旋转日志。
 - `MAX_DAYS`：**7**：在此天数之后删除旋转的日志文件。
 - `COMPRESS`：**true**：默认情况下是否使用 gzip 压缩旧的日志文件。
 - `COMPRESSION_LEVEL`：**-1**：压缩级别。详细信息见下文。
 `MAX_SIZE_SHIFT` 通过将给定次数左移 1 (`1 << x`) 来定义文件的最大大小。
 在 v1.17.3 版本时的确切行为可以在[这里](https://github.com/go-gitea/gitea/blob/v1.17.3/modules/setting/log.go#L185)中查看。
 `COMPRESSION_LEVEL` 的有用值范围从 1 到（包括）9，其中较高的数字表示更好的压缩。
 请注意，更好的压缩可能会带来更高的资源使用。
 必须在前面加上 `-` 符号。
 ### Conn 模式
 在此模式下，日志记录器将通过网络套接字发送日志消息。
 设置：
 - `ADDR`：**:7020**：设置要连接的地址。
 - `PROTOCOL`：**tcp**：设置协议，可以是 "tcp"、"unix" 或 "udp"。
 - `RECONNECT`：**false**：在连接丢失时尝试重新连接。
 - `RECONNECT_ON_MSG`：**false**：为每条消息重新连接主机。
 ### "Router" 日志记录器
 当 Gitea 的路由处理程序工作时，Router 日志记录器记录以下消息类型：
 - `started` 消息将以 TRACE 级别记录
 - `polling`/`completed` 路由将以 INFO 级别记录。异常情况："/assets" 静态资源请求也会以 TRACE 级别记录。
 - `slow` 路由将以 WARN 级别记录
 - `failed` 路由将以 WARN 级别记录
 ### "XORM" 日志记录器
 为了使 XORM 输出 SQL 日志，还应将 `[database]` 部分中的 `LOG_SQL` 设置为 `true`。
 ### "Access" 日志记录器
 "Access" 日志记录器是自 Gitea 1.9 版本以来的新日志记录器。它提供了符合 NCSA Common Log 标准的日志格式。虽然它具有高度可配置性，但在更改其模板时应谨慎。此日志记录器的主要好处是，Gitea 现在可以使用标准日志格式记录访问日志，因此可以使用标准工具进行分析。
 您可以通过使用 `logger.access.MODE = ...` 来启用此日志记录器。
 如果需要，可以通过更改 `ACCESS_LOG_TEMPLATE` 的值来更改 "Access" 日志记录器的格式。
 请注意，访问日志记录器将以 `INFO` 级别记录，将此日志记录器的 `LEVEL` 设置为 `WARN` 或更高级别将导致不记录访问日志。
 #### ACCESS_LOG_TEMPLATE
 此值表示一个 Go 模板。其默认值为
 ```tmpl
 {{.Ctx.RemoteHost}} - {{.Identity}} {{.Start.Format "[02/Jan/2006:15:04:05 -0700]" }} "{{.Ctx.Req.Method}} {{.Ctx.Req.URL.RequestURI}} {{.Ctx.Req.Proto}}" {{.ResponseWriter.Status}} {{.ResponseWriter.Size}} "{{.Ctx.Req.Referer}}" "{{.Ctx.Req.UserAgent}}"`
 ```
 模板接收以下选项：
 - `Ctx` 是 `context.Context`
 - `Identity` 是 `SignedUserName`，如果用户未登录，则为 "-"
 - `Start` 是请求的开始时间
 - `ResponseWriter` 是 `http.ResponseWriter`
 更改此模板时必须小心，因为它在标准的 panic 恢复陷阱之外运行。此模板应该尽可能简单，因为它会为每个请求运行一次。
 ## 释放和重新打开、暂停和恢复日志记录
 如果您在 Unix 上运行，您可能希望释放和重新打开日志以使用 `logrotate` 或其他工具。
 可以通过向运行中的进程发送 `SIGUSR1` 信号或运行 `gitea manager logging release-and-reopen` 命令来强制 Gitea 释放并重新打开其日志文件和连接。
 或者，您可能希望暂停和恢复日志记录 - 可以通过使用 `gitea manager logging pause` 和 `gitea manager logging resume` 命令来实现。请注意，当日志记录暂停时，低于 INFO 级别的日志事件将不会存储，并且只会存储有限数量的事件。在暂停时，日志记录可能会阻塞，尽管是暂时性的，但会大大减慢 Gitea 的运行速度，因此建议仅暂停很短的时间。
 ### 在 Gitea 运行时添加和删除日志记录
 可以使用 `gitea manager logging add` 和 `remove` 子命令在 Gitea 运行时添加和删除日志记录。
 此功能只能调整正在运行的日志系统，不能用于启动未初始化的访问或路由日志记录器。如果您希望启动这些系统，建议调整 app.ini 并（优雅地）重新启动 Gitea 服务。
 这些命令的主要目的是在运行中的系统上轻松添加临时日志记录器，以便调查问题，因为重新启动可能会导致问题消失。
 ## 使用 `logrotate` 而不是内置的日志轮转
 Gitea 包含内置的日志轮转功能，对于大多数部署来说应该已经足够了。但是，如果您想使用 `logrotate` 工具：
 - 在 `app.ini` 中将 `LOG_ROTATE` 设置为 `false`，禁用内置的日志轮转。
 - 安装 `logrotate`。
 - 根据部署要求配置 `logrotate`，有关配置语法细节，请参阅 `man 8 logrotate`。
  在 `postrotate/endscript` 块中通过 `kill -USR1` 或 `kill -10` 向 `gitea` 进程本身发送 `USR1` 信号，
  或者运行 `gitea manager logging release-and-reopen`（使用适当的环境设置）。
  确保配置适用于由 Gitea 日志记录器生成的所有文件，如上述部分所述。
 - 始终使用 `logrotate /etc/logrotate.conf --debug` 来测试您的配置。
 - 如果您正在使用 Docker 并从容器外部运行，您可以使用
  `docker exec -u $OS_USER $CONTAINER_NAME sh -c 'gitea manager logging release-and-reopen'`
  或 `docker exec $CONTAINER_NAME sh -c '/bin/s6-svc -1 /etc/s6/gitea/'`，或直接向 Gitea 进程本身发送 `USR1` 信号。
 下一个 `logrotate` 作业将包括您的配置，因此不需要重新启动。
 您还可以立即使用 `logrotate /etc/logrotate.conf --force` 重新加载 `logrotate`。
@@ -1,254 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 slug: "mail-templates"
 sidebar_position: 45
 aliases:
  - /zh-cn/mail-templates
 ---
 # 邮件模板
 为了定制特定操作的电子邮件主题和内容，可以使用模板来自定义 Gitea。这些功能的模板位于 [`custom` 目录](../administration/customizing-gitea.md) 下。
 如果没有自定义的替代方案，Gitea 将使用内部模板作为默认模板。
 自定义模板在 Gitea 启动时加载。对它们的更改在 Gitea 重新启动之前不会被识别。
 ## 支持模板的邮件通知
 目前，以下通知事件使用模板：
 | 操作名称   | 用途                                                                   |
 | ---------- | ---------------------------------------------------------------------- |
 | `new`      | 创建了新的工单或合并请求。                                             |
 | `comment`  | 在现有工单或合并请求中创建了新的评论。                                 |
 | `close`    | 关闭了工单或合并请求。                                                 |
 | `reopen`   | 重新打开了工单或合并请求。                                             |
 | `review`   | 在合并请求中进行审查的首要评论。                                       |
 | `approve`  | 对合并请求进行批准的首要评论。                                         |
 | `reject`   | 对合并请求提出更改请求的审查的首要评论。                               |
 | `code`     | 关于合并请求的代码的单个评论。                                         |
 | `assigned` | 用户被分配到工单或合并请求。                                           |
 | `default`  | 未包括在上述类别中的任何操作，或者当对应类别的模板不存在时使用的模板。 |
 特定消息类型的模板路径为：
 ```sh
 custom/templates/mail/{操作类型}/{操作名称}.tmpl
 ```
 其中 `{操作类型}` 是 `issue` 或 `pull`（针对合并请求），`{操作名称}` 是上述列出的操作名称之一。
 例如，有关合并请求中的评论的电子邮件的特定模板是：
 ```sh
 custom/templates/mail/pull/comment.tmpl
 ```
 然而，并不需要为每个操作类型/名称组合创建模板。
 使用回退系统来选择适当的模板。在此列表中，将使用 _第一个存在的_ 模板：
 - 所需**操作类型**和**操作名称**的特定模板。
 - 操作类型为 `issue` 和所需**操作名称**的模板。
 - 所需**操作类型**和操作名称为 `default` 的模板。
 - 操作类型为` issue` 和操作名称为 `default` 的模板。
 唯一必需的模板是操作类型为 `issue` 操作名称为 `default` 的模板，除非用户在 `custom` 目录中覆盖了它。
 ## 模板语法
 邮件模板是 UTF-8 编码的文本文件，需要遵循以下格式之一：
 ```
 用于主题行的文本和宏
 ------------
 用于邮件正文的文本和宏
 ```
 或者
 ```
 用于邮件正文的文本和宏
 ```
 指定 _主题_ 部分是可选的（因此也是虚线分隔符）。在使用时，_主题_ 和 _邮件正文_ 模板之间的分隔符需要至少三个虚线；分隔符行中不允许使用其他字符。
 _主题_ 和 _邮件正文_ 由 [Golang 的模板引擎](https://go.dev/pkg/text/template/) 解析，并提供了为每个通知组装的 _元数据上下文_。上下文包含以下元素：
 | 名称               | 类型             | 可用性         | 用途                                                                                                                                                                    |
 | ------------------ | ---------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `.FallbackSubject` | string           | 始终可用       | 默认主题行。参见下文。                                                                                                                                                  |
 | `.Subject`         | string           | 仅在正文中可用 | 解析后的 _主题_。                                                                                                                                                       |
 | `.Body`            | string           | 始终可用       | 工单、合并请求或评论的消息，从 Markdown 解析为 HTML 并进行了清理。请勿与 _邮件正文_ 混淆。                                                                              |
 | `.Link`            | string           | 始终可用       | 源工单、合并请求或评论的地址。                                                                                                                                          |
 | `.Issue`           | models.Issue     | 始终可用       | 产生通知的工单（或合并请求）。要获取特定于合并请求的数据（例如 `HasMerged`），可以使用 `.Issue.PullRequest`，但需要注意，如果工单 _不是_ 合并请求，则该字段将为 `nil`。 |
 | `.Comment`         | models.Comment   | 如果适用       | 如果通知是针对添加到工单或合并请求的评论，则其中包含有关评论的信息。                                                                                                    |
 | `.IsPull`          | bool             | 始终可用       | 如果邮件通知与合并请求关联（即 `.Issue.PullRequest` 不为 `nil` ），则为 `true`。                                                                                        |
 | `.Repo`            | string           | 始终可用       | 仓库的名称，包括所有者名称（例如 `mike/stuff`）                                                                                                                         |
 | `.User`            | models.User      | 始终可用       | 事件来源仓库的所有者。要获取用户名（例如 `mike`），可以使用 `.User.Name`。                                                                                              |
 | `.Doer`            | models.User      | 始终可用       | 执行触发通知事件的操作的用户。要获取用户名（例如 `rhonda`），可以使用 `.Doer.Name`。                                                                                    |
 | `.IsMention`       | bool             | 始终可用       | 如果此通知仅是因为在评论中提到了用户而生成的，并且收件人未订阅源，则为 `true`。如果收件人已订阅工单或仓库，则为 `false`。                                               |
 | `.SubjectPrefix`   | string           | 始终可用       | 如果通知是关于除工单或合并请求创建之外的其他内容，则为 `Re：`；否则为空字符串。                                                                                         |
 | `.ActionType`      | string           | 始终可用       | `"issue"` 或 `"pull"`。它将与实际的 _操作类型_ 对应，与选择的模板无关。                                                                                                 |
 | `.ActionName`      | string           | 始终可用       | 它将是上述操作类型之一（`new` ，`comment` 等），并与选择的模板对应。                                                                                                    |
 | `.ReviewComments`  | []models.Comment | 始终可用       | 审查中的代码评论列表。评论文本将在 `.RenderedContent` 中，引用的代码将在 `.Patch` 中。                                                                                  |
 所有名称区分大小写。
 ### 模板中的主题部分
 用于邮件主题的模板引擎是 Golang 的 [`text/template`](https://go.dev/pkg/text/template/)。
 有关语法的详细信息，请参阅链接的文档。
 主题构建的步骤如下：
 - 根据通知类型和可用的模板选择一个模板。
 - 解析并解析模板（例如，将 `{{.Issue.Index}}` 转换为工单或合并请求的编号）。
 - 将所有空格字符（例如 `TAB`，`LF` 等）转换为普通空格。
 - 删除所有前导、尾随和多余的空格。
 - 将字符串截断为前 256 个字母（字符）。
 如果最终结果为空字符串，**或者**没有可用的主题模板（即所选模板不包含主题部分），将使用 Gitea 的**内部默认值**。
 内部默认（回退）主题相当于：
 ```
 {{.SubjectPrefix}}[{{.Repo}}] {{.Issue.Title}} (#{{.Issue.Index}})
 ```
 例如：`Re: [mike/stuff] New color palette (#38)`
 即使存在有效的主题模板，Gitea 的默认主题也可以在模板的元数据中作为 `.FallbackSubject` 找到。
 ### 模板中的邮件正文部分
 用于邮件正文的模板引擎是 Golang 的 [`html/template`](https://go.dev/pkg/html/template/)。
 有关语法的详细信息，请参阅链接的文档。
 邮件正文在邮件主题之后进行解析，因此还有一个额外的 _元数据_ 字段，即在考虑所有情况之后实际呈现的主题。
 期望的结果是 HTML（包括结构元素，如`<html>`，`<body>`等）。可以通过 `<style>` 块、`class` 和 `style` 属性进行样式设置。但是，`html/template` 会进行一些 [自动转义](https://go.dev/pkg/html/template/#hdr-Contexts)，需要考虑这一点。
 不支持附件（例如图像或外部样式表）。但是，也可以引用其他模板，例如以集中方式提供 `<style>` 元素的内容。外部模板必须放置在 `custom/mail` 下，并相对于该目录引用。例如，可以使用 `{{template styles/base}}` 包含 `custom/mail/styles/base.tmpl`。
 邮件以 `Content-Type: multipart/alternative` 发送，因此正文以 HTML 和文本格式发送。通过剥离 HTML 标记来获取文本版本。
 ## 故障排除
 邮件的呈现方式直接取决于邮件应用程序的功能。许多邮件客户端甚至不支持 HTML，因此显示生成邮件中包含的文本版本。
 如果模板无法呈现，则只有在发送邮件时才会注意到。
 如果主题模板失败，将使用默认主题，如果从 _邮件正文_ 中成功呈现了任何内容，则将使用该内容，忽略其他内容。
 如果遇到问题，请检查 [Gitea 的日志](../administration/logging-config.md) 以获取错误消息。
 ## 示例
 `custom/templates/mail/issue/default.tmpl`:
 ```html
 [{{.Repo}}] @{{.Doer.Name}}
 {{if eq .ActionName "new"}}
    创建了
 {{else if eq .ActionName "comment"}}
    评论了
 {{else if eq .ActionName "close"}}
    关闭了
 {{else if eq .ActionName "reopen"}}
    重新打开了
 {{else}}
    更新了
 {{end}}
 {{if eq .ActionType "issue"}}
    工单
 {{else}}
    合并请求
 {{end}}
 #{{.Issue.Index}}: {{.Issue.Title}}
 ------------
 <!DOCTYPE html>
 <html>
 <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>{{.Subject}}</title>
 </head>
 <body>
    {{if .IsMention}}
    <p>
        您收到此邮件是因为 @{{.Doer.Name}} 提到了您。
    </p>
    {{end}}
    <p>
        <p>
        <a href="{{AppUrl}}/{{.Doer.LowerName}}">@{{.Doer.Name}}</a>
        {{if not (eq .Doer.FullName "")}}
            ({{.Doer.FullName}})
        {{end}}
        {{if eq .ActionName "new"}}
            创建了
        {{else if eq .ActionName "close"}}
            关闭了
        {{else if eq .ActionName "reopen"}}
            重新打开了
        {{else}}
            更新了
        {{end}}
        <a href="{{.Link}}">{{.Repo}}#{{.Issue.Index}}</a>。
        </p>
        {{if not (eq .Body "")}}
            <h3>消息内容：</h3>
            <hr>
            {{.Body}}
        {{end}}
    </p>
    <hr>
    <p>
        <a href="{{.Link}}">在 Gitea 上查看</a>。
    </p>
 </body>
 </html>
 ```
 该模板将生成以下内容：
 ### 主题
 > [mike/stuff] @rhonda 在合并请求 #38 上进行了评论：New color palette
 ### 邮件正文
 > [@rhonda](#)（Rhonda Myers）更新了 [mike/stuff#38](#)。
 >
 > #### 消息内容
 >
 > \_******\*\*******\*\*\*\*******\*\*******\_******\*\*******\*\*\*\*******\*\*******
 >
 > Mike, I think we should tone down the blues a little.
 >
 > \_******\*\*******\*\*\*\*******\*\*******\_******\*\*******\*\*\*\*******\*\*******
 >
 > [在 Gitea 上查看](#)。
 ## 高级用法
 模板系统包含一些函数，可用于进一步处理和格式化消息。以下是其中一些函数的列表：
 | 函数名           | 参数        | 可用于     | 用法                                             |
 | ---------------- | ----------- | ---------- | ------------------------------------------------ |
 | `AppUrl`         | -           | 任何地方   | Gitea 的 URL                                     |
 | `AppName`        | -           | 任何地方   | 从 `app.ini` 中设置，通常为 "Gitea"              |
 | `AppDomain`      | -           | 任何地方   | Gitea 的主机名                                   |
 | `EllipsisString` | string, int | 任何地方   | 将字符串截断为指定长度；根据需要添加省略号       |
 | `SanitizeHTML`   | string      | 仅正文部分 | 通过删除其中的危险 HTML 标签对文本进行清理       |
 | `SafeHTML`       | string      | 仅正文部分 | 将输入作为 HTML 处理；可用于输出原始的 HTML 内容 |
 这些都是 _函数_，而不是元数据，因此必须按以下方式使用：
 ```html
 像这样使用： {{SanitizeHTML "Escape<my
  >text"}} 或者这样使用： {{"Escape<my
    >text" | SanitizeHTML}} 或者这样使用： {{AppUrl}} 但不要像这样使用：
    {{.AppUrl}}</my
  ></my
 >
 ```
@@ -1,50 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 slug: "repo-indexer"
 sidebar_position: 45
 aliases:
  - /zh-cn/repo-indexer
 ---
 # 仓库索引器
 ## 设置仓库索引器
 通过在您的 [`app.ini`](../administration/config-cheat-sheet.md) 中启用此功能，Gitea 可以通过仓库的文件进行搜索：
 ```ini
 [indexer]
 ; ...
 REPO_INDEXER_ENABLED = true
 REPO_INDEXER_PATH = indexers/repos.bleve
 MAX_FILE_SIZE = 1048576
 REPO_INDEXER_INCLUDE =
 REPO_INDEXER_EXCLUDE = resources/bin/**
 ```
 请记住，索引内容可能会消耗大量系统资源，特别是在首次创建索引或全局更新索引时（例如升级 Gitea 之后）。
 ### 按大小选择要索引的文件
 `MAX_FILE_SIZE` 选项将使索引器跳过所有大于指定值的文件。
 ### 按路径选择要索引的文件
 Gitea 使用 [`gobwas/glob` 库](https://github.com/gobwas/glob) 中的 glob 模式匹配来选择要包含在索引中的文件。
 限制文件列表可以防止索引被派生或无关的文件（例如 lss、sym、map 等）污染，从而使搜索结果更相关。这还有助于减小索引的大小。
 `REPO_INDEXER_EXCLUDE_VENDORED`（默认值为 true）将排除供应商文件不包含在索引中。
 `REPO_INDEXER_INCLUDE`（默认值为空）是一个逗号分隔的 glob 模式列表，用于在索引中**包含**的文件。空列表表示“_包含所有文件_”。
 `REPO_INDEXER_EXCLUDE`（默认值为空）是一个逗号分隔的 glob 模式列表，用于从索引中**排除**的文件。与该列表匹配的文件将不会被索引。`REPO_INDEXER_EXCLUDE` 优先于 `REPO_INDEXER_INCLUDE`。
 模式匹配工作方式如下：
 - 要匹配所有带有 `.txt` 扩展名的文件，无论在哪个目录中，请使用 `**.txt`。
 - 要匹配仅在仓库的根级别中具有 `.txt` 扩展名的所有文件，请使用 `*.txt`。
 - 要匹配 `resources/bin` 目录及其子目录中的所有文件，请使用 `resources/bin/**`。
 - 要匹配位于 `resources/bin` 目录下的所有文件，请使用 `resources/bin/*`。
 - 要匹配所有名为 `Makefile` 的文件，请使用 `**Makefile`。
 - 匹配目录没有效果；模式 `resources/bin` 不会包含/排除该目录中的文件；`resources/bin/**` 会。
 - 所有文件和模式都规范化为小写，因此 `**Makefile`、`**makefile` 和 `**MAKEFILE` 是等效的。
@@ -1,454 +0,0 @@
 ---
 date: "2018-05-22T11:00:00+00:00"
 slug: "reverse-proxies"
 sidebar_position: 16
 aliases:
  - /zh-cn/reverse-proxies
 ---
 # 反向代理
 ## 通用配置
 1. 在您的 `app.ini` 文件中添加配置 `[server] ROOT_URL = https://git.example.com/`
 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 会回退为定期轮询。
 ## 使用子路径
 通常，**不推荐**将 Gitea 放到子路径。人们很少使用此配置，并且在极少数情况下可能会出现一些问题。
 为了让 Gitea 在子路径工作（例如：`https://common.example.com/gitea/`），需要在上面的通用配置之外进行一些额外的配置：
 1. 在 `app.ini` 文件中使用配置 `[server] ROOT_URL = https://common.example.com/gitea/`。
 2. 将 `https://common.example.com/gitea/foo` 反向代理到 `http://gitea:3000/foo`。
 3. 容器映像注册表需要在根目录级别有一个固定的子路径 `v2`，您必须做下列配置：
   - 将 `https://common.example.com/v2` 反向代理到 `http://gitea:3000/v2`。
   - 确保 URI 和标头也被正确的传递（见上面的通用配置）
 ## 使用 Nginx 作为反向代理服务
 如果您想使用 Nginx 作为 Gitea 的反向代理服务，您可以参照以下 `nginx.conf` 配置中 `server` 的 `http` 部分。
 确保 `client_max_body_size` 足够大，否则在上传大文件时会出现 "client_max_body_size" 错误。
 ```nginx
 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;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
 }
 ```
 ## 使用 Nginx 作为反向代理服务并将 Gitea 路由至一个子路径
 如果您已经有一个域名并且想与 Gitea 共享该域名，您可以增加以下 `nginx.conf` 配置中 `server` 的 `http` 部分，为 Gitea 添加路由规则：
 ```nginx
 server {
    ...
    location ~ ^/(gitea|v2)($|/) {
        client_max_body_size 512M;
        # 确保 nginx 使用未转义 URI， 按原样保持 "%2F"。 确保 nginx 去除 "/gitea" 子路径前缀， 按原样传递 "/v2"。
        rewrite ^ $request_uri;
        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;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
 }
 ```
 然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。
 ## 使用 Nginx 直接提供静态资源
 我们可以通过将资源分为静态和动态两种类型来调节性能。
 CSS 文件、JavaScript 文件、图片和字体是静态内容。首页、仓库视图和工单列表是动态内容。
 Nginx 可以直接提供静态资源，并且只代理动态资源请求给 Gitea。
 Nginx 为提供静态内容进行了优化，而代理大响应可能与这一优化行为相反。
 （见[https://serverfault.com/q/587386](https://serverfault.com/q/587386)）
 将 Gitea 源代码仓库的一个快照下载到 `/path/to/gitea`。
 在此之后，在本地仓库目录运行 `make frontend` 来生成静态资源。在这个情况下，我们只对 `public/` 目录感兴趣，您可以删除剩下的其他目录。
 （为了生成静态资源，您需要安装一个[带 npm 的 Node ](https://nodejs.org/en/download/)和 `make`）
 取决于您的用户量的大小，您可以将流量分离到两个不同的服务器，或者为静态资源配置一个 cdn。
 ### 单服务器节点，单域名
 将 `[server] STATIC_URL_PREFIX = /_/static` 写入您的 Gitea 配置文件，并配置 nginx：
 ```nginx
 server {
    listen 80;
    server_name git.example.com;
    location /_/static/assets/ {
        alias /path/to/gitea/public/;
    }
    location / {
        # 其他指令见上面「使用 Nginx 作为反向代理服务」小节
        proxy_pass http://localhost:3000;
    }
 }
 ```
 ### 双服务器节点，双域名
 将 `[server] STATIC_URL_PREFIX = http://cdn.example.com/gitea` 写入您的 Gitea 配置文件，并配置 nginx：
 ```nginx
 # 运行 Gitea 的服务器
 server {
    listen 80;
    server_name git.example.com;
    location / {
        # 其他指令见上面「使用 Nginx 作为反向代理服务」小节
        proxy_pass http://localhost:3000;
    }
 }
 ```
 ```nginx
 # 提供静态资源的服务器
 server {
    listen 80;
    server_name cdn.example.com;
    location /gitea/ {
        alias /path/to/gitea/public/;
    }
    location / {
        return 404;
    }
 }
 ```
 ## 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` 目录下）：
 ```apacheconf
 <VirtualHost *:80>
    ...
    ProxyPreserveHost On
    ProxyRequests off
    AllowEncodedSlashes NoDecode
    ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
 </VirtualHost>
 ```
 :::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` 目录下）：
 ```apacheconf
 <VirtualHost *:80>
    ...
    <Proxy *>
         Order allow,deny
         Allow from all
    </Proxy>
    AllowEncodedSlashes NoDecode
    # 注意: 路径和 URL 后面都不要写路径符号 '/'
    ProxyPass /git http://localhost:3000 nocanon upgrade=websocket
    ProxyPreserveHost On
    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
 </VirtualHost>
 ```
 然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。
 :::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 作为反向代理服务
 如果您想使用 Caddy 作为 Gitea 的反向代理服务，您可以在 `Caddyfile` 中添加如下配置：
 ```
 git.example.com {
    reverse_proxy localhost:3000
 }
 ```
 ## 使用 Caddy 作为反向代理服务并将 Gitea 路由至一个子路径
 如果您已经有一个域名并且想与 Gitea 共享该域名，您可以在您的 `Caddyfile` 文件中增加以下配置，为 Gitea 添加路由规则：
 ```
 git.example.com {
    route /git/* {
        uri strip_prefix /git
        reverse_proxy localhost:3000
    }
 }
 ```
 然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。
 ## 使用 IIS 作为反向代理服务
 如果您想使用 IIS 作为 Gitea 的反向代理服务，你需要为 IIS 设置 URL 重写来作为反向代理。
 1. 在 IIS 中设置一个空网页，比如命名为 `Gitea Proxy`。
 2. 根据[微软社区中为 IIS 设置 URL 重写的指南](https://techcommunity.microsoft.com/t5/iis-support-blog/setup-iis-with-url-rewrite-as-a-reverse-proxy-for-real-world/ba-p/846222#M343)的前两步进行配置，也就是：
 - 使用 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
 <?xml version="1.0" encoding="UTF-8"?>
 <configuration>
    <system.web>
        <httpRuntime requestPathInvalidCharacters="" />
    </system.web>
    <system.webServer>
        <security>
          <requestFiltering>
            <hiddenSegments>
              <clear />
            </hiddenSegments>
            <denyUrlSequences>
              <clear />
            </denyUrlSequences>
            <fileExtensions allowUnlisted="true">
              <clear />
            </fileExtensions>
          </requestFiltering>
        </security>
        <rewrite>
            <rules useOriginalURLEncoding="false">
                <rule name="ReverseProxyInboundRule1" stopProcessing="true">
                    <match url="(.*)" />
                    <action type="Rewrite" url="http://127.0.0.1:3000{UNENCODED_URL}" />
                    <serverVariables>
                        <set name="HTTP_X_ORIGINAL_ACCEPT_ENCODING" value="HTTP_ACCEPT_ENCODING" />
                        <set name="HTTP_ACCEPT_ENCODING" value="" />
                    </serverVariables>
                </rule>
            </rules>
            <outboundRules>
                <rule name="ReverseProxyOutboundRule1" preCondition="ResponseIsHtml1">
                    <!-- set the pattern correctly here - if you only want to accept http or https -->
                    <!-- change the pattern and the action value as appropriate -->
                    <match filterByTags="A, Form, Img" pattern="^http(s)?://127.0.0.1:3000/(.*)" />
                    <action type="Rewrite" value="http{R:1}://git.example.com/{R:2}" />
                </rule>
                <rule name="RestoreAcceptEncoding" preCondition="NeedsRestoringAcceptEncoding">
                    <match serverVariable="HTTP_ACCEPT_ENCODING" pattern="^(.*)" />
                    <action type="Rewrite" value="{HTTP_X_ORIGINAL_ACCEPT_ENCODING}" />
                </rule>
                <preConditions>
                    <preCondition name="ResponseIsHtml1">
                        <add input="{RESPONSE_CONTENT_TYPE}" pattern="^text/html" />
                    </preCondition>
                    <preCondition name="NeedsRestoringAcceptEncoding">
                        <add input="{HTTP_X_ORIGINAL_ACCEPT_ENCODING}" pattern=".+" />
                    </preCondition>
                </preConditions>
            </outboundRules>
        </rewrite>
        <urlCompression doDynamicCompression="true" />
        <handlers>
          <clear />
          <add name="StaticFile" path="*" verb="*" modules="StaticFileModule,DefaultDocumentModule,DirectoryListingModule" resourceType="Either" requireAccess="Read" />
        </handlers>
        <!-- Map all extensions to the same MIME type, so all files can be
               downloaded. -->
        <staticContent>
          <clear />
          <mimeMap fileExtension="*" mimeType="application/octet-stream" />
        </staticContent>
    </system.webServer>
 </configuration>
 ```
 ## 使用 HAProxy 作为反向代理服务
 如果您想使用 HAProxy 作为 Gitea 的反向代理服务，您可以将下面的内容加入您的 HAProxy 配置。
 在 frontend 部分加入一个 acl 来将对 gitea.example.com 的请求重定向到正确的后端。
 ```
 frontend http-in
    ...
    acl acl_gitea hdr(host) -i gitea.example.com
    use_backend gitea if acl_gitea
    ...
 ```
 添加之前定义好的 backend 部分
 ```
 backend gitea
    server localhost:3000 check
 ```
 如果您将 http 内容重定向到 https，上面的配置文件也能够使用。只需要记住，在 HAProxy 和 Gitea 之间的连接将由 http 完成，所以你不需要在 Gitea 的配置文件中启用 https。
 ## 使用 HAProxy 作为反向代理服务并将 Gitea 路由至一个子路径
 如果您已经有一个域名并且想与 Gitea 共享该域名，您可以在您的 HAProxy 中加入如下配置，为 Gitea 添加路由规则：
 ```
 frontend http-in
    ...
    acl acl_gitea path_beg /gitea
    use_backend gitea if acl_gitea
    ...
 ```
 在这个配置下，http://example.com/gitea/ 将被重定向到您的 Gitea 实例。
 接下来，对于 backend 部分：
 ```
 backend gitea
    http-request replace-path /gitea\/?(.*) \/\1
    server localhost:3000 check
 ```
 添加的 http-request 在需要的时候会自动加入反斜杠/，并且通过将 http://example.com/gitea 正确设置为根来在内部路径中删除 /gitea，使其能够正常工作。
 然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://example.com/gitea/` 的配置项。
 ## 使用 Traefik 作为反向代理服务
 如果您想使用 traefik 作为 Gitea 的反向代理服务，您可以在 `docker-compose.yaml` 中添加 label 部分（假设使用 docker 作为 traefik 的 provider）：
 ```yaml
 gitea:
  image: docker.io/gitea/gitea
  ...
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.gitea.rule=Host(`example.com`)"
    - "traefik.http.services.gitea-websecure.loadbalancer.server.port=3000"
 ```
 这份配置假设您使用 traefik 来处理 HTTPS 服务，并在其和 Gitea 之间使用 HTTP 进行通信。
 ## 使用 Traefik 作为反向代理服务并将 Gitea 路由至一个子路径
 如果您已经有一个域名并且想与 Gitea 共享该域名，您可以在您的 `docker-compose.yaml` 文件中增加以下配置，为 Gitea 添加路由规则（假设使用 docker 作为 traefik 的 provider）：
 ```yaml
 gitea:
  image: docker.io/gitea/gitea
  ...
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.gitea.rule=Host(`example.com`) && PathPrefix(`/gitea`)"
    - "traefik.http.services.gitea-websecure.loadbalancer.server.port=3000"
    - "traefik.http.middlewares.gitea-stripprefix.stripprefix.prefixes=/gitea"
    - "traefik.http.routers.gitea.middlewares=gitea-stripprefix"
 ```
 这份配置假设您使用 traefik 来处理 HTTPS 服务，并在其和 Gitea 之间使用 HTTP 进行通信。
 然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://example.com/gitea/` 的配置项。
@@ -1,30 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 slug: "search-engines-indexation"
 sidebar_position: 60
 aliases:
  - /zh-cn/search-engines-indexation
 ---
 # 搜索引擎索引
 默认情况下，您的 Gitea 安装将被搜索引擎索引。
 如果您不希望您的仓库对搜索引擎可见，请进一步阅读。
 ## 使用 robots.txt 阻止搜索引擎索引
 为了使 Gitea 为顶级安装提供自定义的`robots.txt`（默认为空的 404），请在 [`custom`文件夹或`CustomPath`]（administration/customizing-gitea.md）中创建一个名为 `public/robots.txt` 的文件。
 有关如何配置 `robots.txt` 的示例，请参考 [https://moz.com/learn/seo/robotstxt](https://moz.com/learn/seo/robotstxt)。
 ```txt
 User-agent: *
 Disallow: /
 ```
 如果您将 Gitea 安装在子目录中，则需要在顶级目录中创建或编辑 `robots.txt`。
 ```txt
 User-agent: *
 Disallow: /gitea/
 ```
@@ -1,137 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 slug: "signing"
 sidebar_position: 50
 aliases:
  - /zh-cn/signing
 ---
 # GPG 提交签名
 Gitea 将通过检查提交是否由 Gitea 数据库中的密钥签名，或者提交是否与 Git 的默认密钥匹配，来验证提供的树中的 GPG 提交签名。
 密钥不会被检查以确定它们是否已过期或撤销。密钥也不会与密钥服务器进行检查。
 如果找不到用于验证提交的密钥，提交将被标记为灰色的未锁定图标。如果提交被标记为红色的未锁定图标，则表示它使用带有 ID 的密钥签名。
 请注意：提交的签署者不必是提交的作者或提交者。
 此功能要求 Git >= 1.7.9，但要实现全部功能，需要 Git >= 2.0.0。
 ## 自动签名
 有许多地方 Gitea 会生成提交：
 - 仓库初始化
 - Wiki 更改
 - 使用编辑器或 API 进行的 CRUD 操作
 - 从合并请求进行合并
 根据配置和服务器信任，您可能希望 Gitea 对这些提交进行签名。
 ## 安装和生成 Gitea 的 GPG 密钥
 如何安装签名密钥由服务器管理员决定。Gitea 目前使用服务器的 `git` 命令生成所有提交，因此将使用服务器的 `gpg` 进行签名（如果配置了）。管理员应该审查 GPG 的最佳实践 - 特别是可能建议仅安装签名的子密钥，而不是主签名和认证的密钥。
 ## 通用配置
 Gitea 的签名配置可以在 `app.ini` 的 `[repository.signing]` 部分找到：
 ```ini
 ...
 [repository.signing]
 SIGNING_KEY = default
 SIGNING_NAME =
 SIGNING_EMAIL =
 INITIAL_COMMIT = always
 CRUD_ACTIONS = pubkey, twofa, parentsigned
 WIKI = never
 MERGES = pubkey, twofa, basesigned, commitssigned
 ...
 ```
 ### `SIGNING_KEY`
 首先讨论的选项是 `SIGNING_KEY`。有三个主要选项：
 - `none` - 这将阻止 Gitea 对任何提交进行签名
 - `default` - Gitea 将使用 `git config` 中配置的默认密钥
 - `KEYID` - Gitea 将使用具有 ID `KEYID` 的 GPG 密钥对提交进行签名。在这种情况下，您应该提供 `SIGNING_NAME` 和 `SIGNING_EMAIL`，以便显示此密钥的信息。
 `default` 选项将读取 `git config` 中的 `commit.gpgsign` 选项 - 如果设置了该选项，它将使用 `user.signingkey`、`user.name` 和 `user.email` 的结果。
 通过在 Gitea 的仓库中调整 Git 的 `config` 文件，可以使用 `SIGNING_KEY=default` 为每个仓库提供不同的签名密钥。然而，这显然不是一个理想的用户界面，因此可能会发生更改。
 :::warning
 **自 1.17 起**，Gitea 在自己的主目录 `[git].HOME_PATH`（默认为 `%(APP_DATA_PATH)/home`）中运行 git，并使用自己的配置文件 `{[git].HOME_PATH}/.gitconfig`。
 如果您有自己定制的 Gitea git 配置，您应该将这些配置设置在系统 git 配置文件中（例如 `/etc/gitconfig`）或者 Gitea 的内部 git 配置文件 `{[git].HOME_PATH}/.gitconfig` 中。
 与 git 命令相关的主目录文件（如 `.gnupg`）也应该放在 Gitea 的 git 主目录 `[git].HOME_PATH` 中。
 如果您希望将 `.gnupg` 目录放在 `{[git].HOME_PATH}/` 之外的位置，请考虑设置 `$GNUPGHOME` 环境变量为您首选的位置，否则 Gitea 将会从 `{[git].HOME_PATH}/.gnupg` 查找私钥。
 :::
 ### `INITIAL_COMMIT`
 此选项确定在创建仓库时，Gitea 是否应该对初始提交进行签名。可能的取值有：
 - `never`：从不签名
 - `pubkey`：仅在用户拥有公钥时进行签名
 - `twofa`：仅在用户使用 2FA 登录时进行签名
 - `always`：始终签名
 除了 `never` 和 `always` 之外的选项可以组合为逗号分隔的列表。如果所有选择的选项都为 true，则提交将被签名。
 ### `WIKI`
 此选项确定 Gitea 是否应该对 Wiki 的提交进行签名。可能的取值有：
 - `never`：从不签名
 - `pubkey`：仅在用户拥有公钥时进行签名
 - `twofa`：仅在用户使用 2FA 登录时进行签名
 - `parentsigned`：仅在父提交已签名时进行签名。
 - `always`：始终签名
 除了 `never` 和 `always` 之外的选项可以组合为逗号分隔的列表。如果所有选择的选项都为 true，则提交将被签名。
 ### `CRUD_ACTIONS`
 此选项确定 Gitea 是否应该对 Web 编辑器或 API CRUD 操作的提交进行签名。可能的取值有：
 - `never`：从不签名
 - `pubkey`：仅在用户拥有公钥时进行签名
 - `twofa`：仅在用户使用 2FA 登录时进行签名
 - `parentsigned`：仅在父提交已签名时进行签名。
 - `always`：始终签名
 除了 `never` 和 `always` 之外的选项可以组合为逗号分隔的列表。如果所有选择的选项都为 true，则更改将被签名。
 ### `MERGES`
 此选项确定 Gitea 是否应该对 PR 的合并提交进行签名。可能的选项有：
 - `never`：从不签名
 - `pubkey`：仅在用户拥有公钥时进行签名
 - `twofa`：仅在用户使用 2FA 登录时进行签名
 - `basesigned`：仅在基础仓库中的父提交已签名时进行签名。
 - `headsigned`：仅在头分支中的头提交已签名时进行签名。
 - `commitssigned`：仅在头分支中的所有提交到合并点的提交都已签名时进行签名。
 - `approved`：仅对已批准的合并到受保护分支的提交进行签名。
 - `always`：始终签名
 除了 `never` 和 `always` 之外的选项可以组合为逗号分隔的列表。如果所有选择的选项都为 true，则合并将被签名。
 ## 获取签名密钥的公钥
 用于签署 Gitea 提交的公钥可以通过 API 获取：
 ```sh
 /api/v1/signing-key.gpg
 ```
 在存在特定于仓库的密钥的情况下，可以通过以下方式获取：
 ```sh
 /api/v1/repos/:username/:reponame/signing-key.gpg
 ```
@@ -1,9 +0,0 @@
 {
  "label": "贡献",
  "position": 35,
  "link": {
    "type": "generated-index",
    "slug": "/contributing",
    "title": "贡献"
  }
 }
@@ -1,110 +0,0 @@
 ---
 date: "2023-05-25T23:41:00+08:00"
 slug: "guidelines-backend"
 sidebar_position: 20
 aliases:
  - /zh-cn/guidelines-backend
 ---
 # 后端开发指南
 ## 背景
 Gitea 使用 Golang 作为后端编程语言。它使用了许多第三方包，并且自己也编写了一些包。
 例如，Gitea 使用[Chi](https://github.com/go-chi/chi)作为基本的 Web 框架。[Xorm](https://xorm.io)是一个用于与数据库交互的 ORM 框架。
 因此，管理这些包非常重要。在开始编写后端代码之前，请参考以下准则。
 ## 包设计准则
 ### 包列表
 为了保持易于理解的代码并避免循环依赖，拥有良好的代码结构是很重要的。Gitea 后端分为以下几个部分：
 - `build`：帮助构建 Gitea 的脚本。
 - `cmd`：包含所有 Gitea 的实际子命令，包括 web、doctor、serv、hooks、admin 等。`web`将启动 Web 服务。`serv`和`hooks`将被 Git 或 OpenSSH 调用。其他子命令可以帮助维护 Gitea。
 - `tests`：常用的测试函数
 - `tests/integration`：集成测试，用于测试后端回归。
 - `tests/e2e`：端到端测试，用于测试前端和后端的兼容性和视觉回归。
 - `models`：包含由 xorm 用于构建数据库表的数据结构。它还包含查询和更新数据库的函数。应避免与其他 Gitea 代码的依赖关系。在某些情况下，比如日志记录时可以例外。
  - `models/db`：基本的数据库操作。所有其他`models/xxx`包都应依赖于此包。`GetEngine`函数只能从 models/中调用。
  - `models/fixtures`：单元测试和集成测试中使用的示例数据。一个`yml`文件表示一个将在测试开始时加载到数据库中的表。
  - `models/migrations`：存储不同版本之间的数据库迁移。修改数据库结构的 PR**必须**包含一个迁移步骤。
 - `modules`：在 Gitea 中处理特定功能的不同模块。工作正在进行中：其中一些模块应该移到`services`中，特别是那些依赖于 models 的模块，因为它们依赖于数据库。
  - `modules/setting`：存储从 ini 文件中读取的所有系统配置，并在各处引用。但是在可能的情况下，应将其作为函数参数使用。
  - `modules/git`：用于与`Git`命令行或 Gogit 包交互的包。
 - `public`：编译后的前端文件（JavaScript、图像、CSS 等）
 - `routers`：处理服务器请求。由于它使用其他 Gitea 包来处理请求，因此其他包（models、modules 或 services）不能依赖于 routers。
  - `routers/api`：包含`/api/v1`相关路由，用于处理 RESTful API 请求。
  - `routers/install`：只能在系统处于安装模式（INSTALL_LOCK=false）时响应。
  - `routers/private`：仅由内部子命令调用，特别是`serv`和`hooks`。
  - `routers/web`：处理来自 Web 浏览器或 Git SMART HTTP 协议的 HTTP 请求。
 - `services`：用于常见路由操作或命令执行的支持函数。使用`models`和`modules`来处理请求。
 - `templates`：用于生成 HTML 输出的 Golang 模板。
 ### 包依赖关系
 由于 Golang 不支持导入循环，我们必须仔细决定包之间的依赖关系。这些包之间有一些级别。以下是理想的包依赖关系方向。
 `cmd` -> `routers` -> `services` -> `models` -> `modules`
 从左到右，左侧的包可以依赖于右侧的包，但右侧的包不能依赖于左侧的包。在同一级别的子包中，可以根据该级别的规则进行依赖。
 **注意事项**
 为什么我们需要在`models`之外使用数据库事务？以及如何使用？
 某些操作在数据库记录插入/更新/删除失败时应该允许回滚。
 因此，服务必须能够创建数据库事务。以下是一些示例：
 ```go
 // services/repository/repository.go
 func CreateXXXX() error {
    return db.WithTx(func(ctx context.Context) error {
        // do something, if err is returned, it will rollback automatically
        if err := issues.UpdateIssue(ctx, repoID); err != nil {
            // ...
            return err
        }
        // ...
        return nil
    })
 }
 ```
 在`services`中**不应该**直接使用`db.GetEngine(ctx)`，而是应该在`models/`下编写一个函数。
 如果该函数将在事务中使用，请将`context.Context`作为函数的第一个参数。
 ```go
 // models/issues/issue.go
 func UpdateIssue(ctx context.Context, repoID int64) error {
    e := db.GetEngine(ctx)
    // ...
 }
 ```
 ### 包名称
 对于顶层包，请使用复数作为包名，例如`services`、`models`，对于子包，请使用单数，例如`services/user`、`models/repository`。
 ### 导入别名
 由于有一些使用相同包名的包，例如`modules/user`、`models/user`和`services/user`，当这些包在一个 Go 文件中被导入时，很难知道我们使用的是哪个包以及它是变量名还是导入名。因此，我们始终建议使用导入别名。为了与常见的驼峰命名法的包变量区分开，建议使用**snake_case**作为导入别名的命名规则。
 例如：`import user_service "code.gitea.io/gitea/services/user"`
 ### 重要注意事项
 - 永远不要写成`x.Update(exemplar)`，而没有明确的`WHERE`子句：
  - 这将导致表中的所有行都被使用 exemplar 的非零值进行更新，包括 ID。
  - 通常应该写成`x.ID(id).Update(exemplar)`。
 - 如果在迁移过程中使用`x.Insert(exemplar)`向表中插入记录，而 ID 是预设的：
  - 对于 MSSQL 变体，你将需要执行`` SET IDENTITY_INSERT `table` ON ``（否则迁移将失败）
  - 对于 PostgreSQL，你还需要更新 ID 序列，否则迁移将悄无声息地通过，但后续的插入将失败：
    `` SELECT setval('table_name_id_seq', COALESCE((SELECT MAX(id)+1 FROM `table_name`), 1), false) ``
 ### 未来的任务
 目前，我们正在进行一些重构，以完成以下任务：
 - 纠正不符合规则的代码。
 - `models`中的文件太多了，所以我们正在将其中的一些移动到子包`models/xxx`中。
 - 由于它们依赖于`models`，因此应将某些`modules`子包移动到`services`中。
@@ -1,149 +0,0 @@
 ---
 date: "2023-05-25T16:00:00+02:00"
 slug: "guidelines-frontend"
 sidebar_position: 20
 aliases:
  - /zh-cn/guidelines-frontend
 ---
 # 前端开发指南
 ## 背景
 Gitea 在其前端中使用[Fomantic-UI](https://fomantic-ui.com/introduction/getting-started.html)（基于[jQuery](https://api.jquery.com)）和 [Vue3](https://vuejs.org/)。
 HTML 页面由[Go HTML Template](https://pkg.go.dev/html/template)渲染。
 源文件可以在以下目录中找到：
 - **CSS 样式**： `web_src/css/`
 - **JavaScript 文件**： `web_src/js/`
 - **Vue 组件**： `web_src/js/components/`
 - **Go HTML 模板**： `templates/`
 ## 通用准则
 我们推荐使用[Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html)和[Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)。
 ## Gitea 特定准则
 1. 每个功能（Fomantic-UI/jQuery 模块）应放在单独的文件/目录中。
 2. HTML 的 id 和 class 应使用 kebab-case，最好包含 2-3 个与功能相关的关键词。
 3. 在 JavaScript 中使用的 HTML 的 id 和 class 应在整个项目中是唯一的，并且应包含 2-3 个与功能相关的关键词。建议在仅在 JavaScript 中使用的 class 中使用 `js-` 前缀。
 4. 不应覆盖框架提供的 class 的 CSS 样式。始终使用具有 2-3 个与功能相关的关键词的新 class 名称来覆盖框架样式。Gitea 中的帮助 CSS 类在 `helpers.less` 中。
 5. 后端可以通过使用`ctx.PageData["myModuleData"] = map[]{}`将复杂数据传递给前端，但不要将整个模型暴露给前端，以避免泄露敏感数据。
 6. 简单页面和与 SEO 相关的页面使用 Go HTML 模板渲染生成静态的 Fomantic-UI HTML 输出。复杂页面可以使用 Vue3。
 7. 明确变量类型，优先使用`elem.disabled = true`而不是`elem.setAttribute('disabled', 'anything')`，优先使用`$el.prop('checked', var === 'yes')`而不是`$el.prop('checked', var)`。
 8. 使用语义化元素，优先使用`<button class="ui button">`而不是`<div class="ui button">`。
 9. 避免在 CSS 中使用不必要的`!important`，如果无法避免，添加注释解释为什么需要它。
 10. 避免在一个事件监听器中混合不同的事件，优先为每个事件使用独立的事件监听器。
 11. 推荐使用自定义事件名称前缀`ce-`。
 12. 建议使用 Tailwind CSS，它可以通过 `tw-` 前缀获得，例如 `tw-relative`. Gitea 自身的助手类 CSS 使用 `gt-` 前缀（`gt-ellipsis`），Gitea 自身的私有框架级 CSS 类使用 `g-` 前缀（`g-modal-confirm`）。
 13. 尽量避免内联脚本和样式，建议将 JS 代码放入 JS 文件中并使用 CSS 类。如果内联脚本和样式不可避免，请解释无法避免的原因。
 ### 可访问性 / ARIA
 在历史上，Gitea 大量使用了可访问性不友好的框架 Fomantic UI。
 Gitea 使用一些补丁使 Fomantic UI 更具可访问性（参见 `aria.md`），
 但仍然存在许多问题需要大量的工作和时间来修复。
 ### 框架使用
 不建议混合使用不同的框架，这会使代码难以维护。
 一个 JavaScript 模块应遵循一个主要框架，并遵循该框架的最佳实践。
 推荐的实现方式：
 - Vue + Vanilla JS
 - Fomantic-UI（jQuery）
 - htmx （部分页面重新加载其他静态组件）
 - Vanilla JS
 不推荐的实现方式：
 - Vue + Fomantic-UI（jQuery）
 - jQuery + Vanilla JS
 - htmx + 任何其他需要大量 JavaScript 代码或不必要的功能，如 htmx 脚本 (`hx-on`)
 为了保持界面一致，Vue 组件可以使用 Fomantic-UI 的 CSS 类。
 尽管不建议混合使用不同的框架，
 我们使用 htmx 进行简单的交互。您可以在此 [PR](https://github.com/go-gitea/gitea/pull/28908) 中查看一个简单交互的示例，其中应使用 htmx。如果您需要更高级的反应性，请不要使用 htmx，请使用其他框架（Vue/Vanilla JS）。
 但如果混合使用是必要的，并且代码设计良好且易于维护，也可以工作。
 ### `async` 函数
 只有当函数内部存在`await`调用或返回`Promise`时，才将函数标记为`async`。
 不建议使用`async`事件监听器，这可能会导致问题。
 原因是`await`后的代码在事件分发之外执行。
 参考：https://github.com/github/eslint-plugin-github/blob/main/docs/rules/async-preventdefault.md
 如果一个事件监听器必须是`async`，应在任何`await`之前使用`e.preventDefault()`，
 建议将其放在函数的开头。
 如果我们想在非异步上下文中调用`async`函数，
 建议使用`const _promise = asyncFoo()`来告诉读者
 这是有意为之的，我们想调用异步函数并忽略 Promise。
 一些 lint 规则和 IDE 也会在未处理返回的 Promise 时发出警告。
 ### 获取数据
 要获取数据，请使用`modules/fetch.js`中的包装函数`GET`、`POST`等。他们
 接受内容的`data`选项，将自动设置 CSRF 令牌并返回
 [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response)。
 ### HTML 属性和 dataset
 禁止使用`dataset`，它的驼峰命名行为使得搜索属性变得困难。
 然而，仍然存在一些特殊情况，因此当前的准则是：
 - 对于旧代码：
  - 应将`$.data()`重构为`$.attr()`。
  - 在极少数情况下，可以使用`$.data()`将一些非字符串数据绑定到元素上，但强烈不推荐使用。
 - 对于新代码：
  - 不应使用`node.dataset`，而应使用`node.getAttribute`。
  - 不要将任何用户数据绑定到 DOM 节点上，使用合适的设计模式描述节点和数据之间的关系。
 ### 显示/隐藏元素
 - 推荐在 Vue 组件中使用`v-if`和`v-show`来显示/隐藏元素。
 - Go 模板代码应使用 `.tw-hidden` 和 `showElem()/hideElem()/toggleElem()` 来显示/隐藏元素，请参阅`.tw-hidden`的注释以获取更多详细信息。
 ### Go HTML 模板中的样式和属性
 建议使用以下方式：
 ```html
 <div
  class="gt-name1 gt-name2 {{if .IsFoo}}gt-foo{{end}}"
  {{if
  .IsFoo}}data-foo{{end}}
 ></div>
 ```
 而不是：
 ```html
 <div
  class="gt-name1 gt-name2{{if .IsFoo}} gt-foo{{end}}"
  {{if
  .IsFoo}}
  data-foo{{end}}
 ></div>
 ```
 以使代码更易读。
 ### 旧代码
 许多旧代码已经存在于本文撰写之前。建议重构旧代码以遵循指南。
 ### Vue3 和 JSX
 Gitea 现在正在使用 Vue3。我们决定不引入 JSX，以保持 HTML 代码和 JavaScript 代码分离。
 ### UI 示例
 Gitea 使用一些自制的 UI 元素并自定义其他元素，以将它们更好地集成到通用 UI 方法中。当在开发模式（`RUN_MODE=dev`）下运行 Gitea 时，在 `http(s)://your-gitea-url:port/devtest` 下会提供一个包含一些标准化 UI 示例的页面。
@@ -1,40 +0,0 @@
 ---
 date: "2023-05-25T00:00:00+00:00"
 slug: "guidelines-refactoring"
 sidebar_position: 20
 aliases:
  - /zh-cn/guidelines-refactoring
 ---
 # 重构指南
 ## 背景
 自 2014 年 2 月 12 日编写了第一行代码以来，Gitea 已经发展成为一个庞大的项目。
 因此，代码库变得越来越大。代码库越大，维护就越困难。
 存在许多过时的机制，许多框架混合在一起，一些遗留代码可能会导致错误并阻碍新功能的开发。
 为了使代码库更易于维护，使 Gitea 变得更好，开发人员应牢记使用现代机制来重构旧代码。
 本文档是关于重构代码库的指南集合。
 ## 重构建议
 - 设计更多关于未来的内容，而不仅仅解决当前问题。
 - 减少模糊性，减少冲突，提高可维护性。
 - 描述重构，例如：
  - 为什么需要重构。
  - 如何解决旧问题。
  - 重构的优点/缺点是什么。
 - 只做必要的更改，尽量保留旧逻辑。
 - 引入一些中间步骤，使重构更容易审查，完整的重构计划可以在几个 PR 中完成。
 - 如果存在分歧，应该请 TOC（技术监督委员会）参与决策。
 - 添加必要的测试以确保重构的正确性。
 - 非错误重构优先在里程碑的开始时进行，这样可以更容易地在发布之前发现问题。
 ## 审查和合并建议
 - 重构的 PR 不应该长时间保持打开状态（通常为 7 天），应尽快进行审查。
 - 重构的 PR 应尽快合并，不应被其他 PR 阻塞。
 - 如果 TOC 没有异议，重构的 PR 可以在 7 天后由一名核心成员（非作者）批准后合并。
 - 如果最终结果良好，容忍一些不完美/临时的步骤。
 - 如果重构是必要的，容忍一些回归错误，并尽快修复错误。
@@ -1,25 +0,0 @@
 ---
 date: "2016-12-01T16:00:00+02:00"
 slug: "localization"
 sidebar_position: 70
 aliases:
  - /zh-cn/localization
 ---
 # 本地化
 Gitea 的本地化是通过我们的[Crowdin 项目](https://crowdin.com/project/gitea)进行的。
 对于对**英语翻译**的更改，可以发出 pull-request，来更改[英语语言环境](https://github.com/go-gitea/gitea/blob/main/options/locale/locale_en-US.ini)中合适的关键字。
 有关对**非英语**翻译的更改，请参阅上面的 Crowdin 项目。
 ## 支持的语言
 上述 Crowdin 项目中列出的任何语言一旦翻译了 25% 或更多都将得到支持。
 翻译被接受后，它将在下一次 Crowdin 同步后反映在主存储库中，这通常是在任何 PR 合并之后。
 在撰写本文时，这意味着更改后的翻译可能要到 Gitea 的下一个版本才会出现。
 如果使用开发版本，则在同步更改内容后，它应该会在更新后立即显示。
@@ -1,9 +0,0 @@
 {
  "label": "开发",
  "position": 40,
  "link": {
    "type": "generated-index",
    "slug": "/development",
    "title": "开发"
  }
 }
@@ -1,334 +0,0 @@
 ---
 date: "2016-12-01T16:00:00+02:00"
 slug: "hacking-on-gitea"
 sidebar_position: 10
 aliases:
  - /zh-cn/hacking-on-gitea
 ---
 # 玩转 Gitea
 ## 快速入门
 要获得快速工作的开发环境，您可以使用 Gitpod。
 [![在 Gitpod 中打开](/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/go-gitea/gitea)
 ## 安装 Golang
 您需要 [安装 go](https://go.dev/doc/install) 并设置您的 go 环境。
 接下来，[使用 npm 安装 Node.js](https://nodejs.org/en/download/) ，这是构建
 JavaScript 和 CSS 文件的必要工具。最低支持的 Node.js 版本是 @minNodeVersion@
 并且推荐使用最新的 LTS 版本。
 **注意** ：当执行需要外部工具的 make 任务时，比如
 `make watch-backend`，Gitea 会自动下载并构建这些必要的组件。为了能够使用这些，你必须
 将 `"$GOPATH"/bin` 目录加入到可执行路径上。如果你不把 go bin 目录添加到可执行路径你必须手动
 指定可执行程序路径。
 **注意 2** ：Go 版本 @minGoVersion@ 或更高版本是必须的。Gitea 使用 `gofmt` 来
 格式化源代码。然而，`gofmt` 的结果可能因 `go` 的版本而有差异。因此推荐安装我们持续集成使用
 的 Go 版本。截至上次更新，Go 版本应该是 @goVersion@。
 ## 安装 Make
 Gitea 大量使用 `Make` 来自动化任务和改进开发。本指南涵盖了如何安装 Make。
 ### 在 Linux 上
 使用包管理器安装。
 在 Ubuntu/Debian 上：
 ```bash
 sudo apt-get install make
 ```
 在 Fedora/RHEL/CentOS 上：
 ```bash
 sudo yum install make
 ```
 ### 在 Windows 上
 Make 的这三个发行版都可以在 Windows 上运行：
 - [单个二进制构建](http://www.equation.com/servlet/equation.cmd?fa=make)。复制到某处并添加到 `PATH`。
  - [32 位版本](http://www.equation.com/ftpdir/make/32/make.exe)
  - [64 位版本](http://www.equation.com/ftpdir/make/64/make.exe)
 - [MinGW-w64](https://www.mingw-w64.org) / [MSYS2](https://www.msys2.org/)。
  - MSYS2 是一个工具和库的集合，为您提供一个易于使用的环境来构建、安装和运行本机 Windows 软件，它包括 MinGW-w64。
  - 在 MingGW-w64 中，二进制文件称为 `mingw32-make.exe` 而不是 `make.exe`。将 `bin` 文件夹添加到 `PATH`。
  - 在 MSYS2 中，您可以直接使用 `make`。请参阅 [MSYS2 移植](https://www.msys2.org/wiki/Porting/)。
  - 要使用 CGO_ENABLED（例如：SQLite3）编译 Gitea，您可能需要使用 [tdm-gcc](https://jmeubank.github.io/tdm-gcc/) 而不是 MSYS2 gcc，因为 MSYS2 gcc 标头缺少一些 Windows -只有 CRT 函数像 \_beginthread 一样。
 - [Chocolatey 包管理器](https://chocolatey.org/packages/make)。运行`choco install make`
 **注意** ：如果您尝试在 Windows 命令提示符下使用 make 进行构建，您可能会遇到问题。建议使用上述提示（Git bash 或 MinGW），但是如果您只有命令提示符（或可能是 PowerShell），则可以使用 [set](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1) 命令，例如 `set TAGS=bindata`。
 ## 下载并克隆 Gitea 源代码
 获取源代码的推荐方法是使用 `git clone`。
 ```bash
 git clone https://github.com/go-gitea/gitea
 ```
 （自从 go modules 出现后，不再需要构建 go 项目从 `$GOPATH` 中获取，因此不再推荐使用 `go get` 方法。）
 ## 派生 Gitea
 如上所述下载主要的 Gitea 源代码。然后，派生 [Gitea 仓库](https://github.com/go-gitea/gitea)，
 并为您的本地仓库切换 git 远程源，或添加另一个远程源：
 ```bash
 # 将原来的 Gitea origin 重命名为 upstream
 git remote rename origin upstream
 git remote add origin "git@github.com:$GITHUB_USERNAME/gitea.git"
 git fetch --all --prune
 ```
 或者：
 ```bash
 # 为我们的 fork 添加新的远程
 git remote add "$FORK_NAME" "git@github.com:$GITHUB_USERNAME/gitea.git"
 git fetch --all --prune
 ```
 为了能够创建合并请求，应将分叉存储库添加为 Gitea 本地仓库的远程，否则无法推送更改。
 ## 构建 Gitea（基本）
 看看我们的
 [说明](installation/from-source.md)
 关于如何[从源代码构建](installation/from-source.md) 。
 从源代码构建的最简单推荐方法是：
 ```bash
 TAGS="bindata sqlite sqlite_unlock_notify" make build
 ```
 `build` 目标将同时执行 `frontend` 和 `backend` 子目标。如果存在 `bindata` 标签，资源文件将被编译成二进制文件。建议在进行前端开发时省略 `bindata` 标签，以便实时反映更改。
 有关所有可用的 `make` 目标，请参阅 `make help`。另请参阅 [`.drone.yml`](https://github.com/go-gitea/gitea/blob/main/.drone.yml) 以了解我们的持续集成是如何工作的。
 ## 持续构建
 要在源文件更改时运行并持续构建：
 ```bash
 # 对于前端和后端
 make watch
 # 或者：只看前端文件（html/js/css）
 make watch-frontend
 # 或者：只看后端文件 (go)
 make watch-backend
 ```
 在 macOS 上，监视所有后端源文件可能会达到默认的打开文件限制，这可以通过当前 shell 的 `ulimit -n 12288` 或所有未来 shell 的 shell 启动文件来增加。
 ### 格式化、代码分析和拼写检查
 我们的持续集成将拒绝未通过代码检查（包括格式检查、代码分析和拼写检查）的 PR。
 你应该格式化你的代码：
 ```bash
 make fmt
 ```
 并检查源代码：
 ```bash
 # lint 前端和后端代码
 make lint
 # 仅 lint 后端代码
 make lint-backend
 ```
 **注意** ：`gofmt` 的结果取决于 `go` 的版本。您应该运行与持续集成相同的 go 版本。
 ### 处理 JS 和 CSS
 前端开发应遵循 [Guidelines for Frontend Development](contributing/guidelines-frontend.md)。
 要使用前端资源构建，请使用上面提到的“watch-frontend”目标或只构建一次：
 ```bash
 make build && ./gitea
 ```
 在提交之前，确保 linters 通过：
 ```bash
 make lint-frontend
 ```
 ### 配置本地 ElasticSearch 实例
 使用 docker 启动本地 ElasticSearch 实例：
 ```sh
 mkdir -p $(pwd) /data/elasticsearch
 sudo chown -R 1000:1000 $(pwd) /data/elasticsearch
 docker run --rm --memory= "4g" -p 127.0.0.1:9200:9200 -p 127.0.0.1:9300:9300 -e "discovery.type=single-node" -v "$(pwd)/data /elasticsearch:/usr/share/elasticsearch/data" docker.elastic.co/elasticsearch/elasticsearch:7.16.3
 ```
 配置`app.ini`：
 ```ini
 [indexer]
 ISSUE_INDEXER_TYPE = elasticsearch
 ISSUE_INDEXER_CONN_STR = http://elastic:changeme@localhost:9200
 REPO_INDEXER_ENABLED = true
 REPO_INDEXER_TYPE = elasticsearch
 REPO_INDEXER_CONN_STR = http://elastic:changeme@localhost:9200
 ```
 ### 构建和添加 SVGs
 SVG 图标是使用 `make svg` 命令构建的，该命令将图标资源编译到输出目录 `public/assets/img/svg` 中。可以在 `web_src/svg` 目录中添加自定义图标。
 ### 构建 Logo
 Gitea Logo 的 PNG 和 SVG 版本是使用 `TAGS="gitea" make generate-images` 目标从单个 SVG 源文件 assets/logo.svg 构建的。要运行它，Node.js 和 npm 必须可用。
 通过更新 `assets/logo.svg` 并运行 `make generate-images`，同样的过程也可用于从 SVG 源文件生成自定义 Logo PNG。忽略 gitea 编译选项将仅更新用户指定的 LOGO 文件。
 ### 更新 API
 创建新的 API 路由或修改现有的 API 路由时，您**必须**
 更新和/或创建 [Swagger](https://swagger.io/docs/specification/2-0/what-is-swagger/)
 这些使用 [go-swagger](https://goswagger.io/) 评论的文档。
 [规范](https://goswagger.io/use/spec.html#annotation-syntax)中描述了这些注释的结构。
 如果您想了解更多有关 Swagger 结构的信息，可以查看
 [Swagger 2.0 文档](https://swagger.io/docs/specification/2-0/basic-structure/)
 或与添加新 API 端点的先前 PR 进行比较，例如 [PR #5483](https://github.com/go-gitea/gitea/pull/5843/files#diff-2e0a7b644cf31e1c8ef7d76b444fe3aaR20)
 您应该注意不要破坏下游用户依赖的 API。在稳定的 API 上，一般来说添加是可以接受的，但删除
 或对 API 进行根本性更改将会被拒绝。
 创建或更改 API 端点后，请用以下命令重新生成 Swagger 文档：
 ```bash
 make generate-swagger
 ```
 您应该验证生成的 Swagger 文件：
 ```bash
 make swagger-validate
 ```
 您应该提交更改后的 swagger JSON 文件。持续集成服务器将使用以下方法检查是否已完成：
 ```bash
 make swagger-check
 ```
 **注意** ：请注意，您应该使用 Swagger 2.0 文档，而不是 OpenAPI 3 文档。
 ### 创建新的配置选项
 创建新的配置选项时，将它们添加到 `modules/setting` 的对应文件。您应该将信息添加到 `custom/conf/app.ini`
 并到[配置备忘单](../administration/config-cheat-sheet.md)
 在 `docs/content/doc/advanced/config-cheat-sheet.zh-cn.md` 中找到
 ### 更改 Logo
 更改 Gitea Logo SVG 时，您将需要运行并提交结果的：
 ```bash
 make generate-images
 ```
 这将创建必要的 Gitea 图标和其他图标。
 ### 数据库迁移
 如果您对数据库中的任何数据库持久结构进行重大更改
 `models/` 目录，您将需要进行新的迁移。可以找到这些
 在 `models/migrations/` 中。您可以确保您的迁移适用于主要
 数据库类型使用：
 ```bash
 make test-sqlite-migration # 将 SQLite 切换为适当的数据库
 ```
 ## 测试
 Gitea 运行两种类型的测试：单元测试和集成测试。
 ### 单元测试
 `go test` 系统中的`*_test.go` 涵盖了单元测试。
 您可以设置环境变量 `GITEA_UNIT_TESTS_LOG_SQL=1` 以在详细模式下运行测试时显示所有 SQL 语句（即设置`GOTESTFLAGS=-v` 时）。
 ```bash
 TAGS="bindata sqlite sqlite_unlock_notify" make test # Runs the unit tests
 ```
 ### 集成测试
 单元测试不会也不能完全单独测试 Gitea。因此，我们编写了集成测试；但是，这些依赖于数据库。
 ```bash
 TAGS="bindata sqlite sqlite_unlock_notify" make build test-sqlite
 ```
 将在 SQLite 环境中运行集成测试。集成测试需要安装 `git lfs`。其他数据库测试可用，但
 可能需要适应当地环境。
 看看 [`tests/integration/README.md`](https://github.com/go-gitea/gitea/blob/main/tests/integration/README.md) 有关更多信息以及如何运行单个测试。
 ### 测试 PR
 我们的持续集成将测试代码是否通过了单元测试，并且所有支持的数据库都将在 Docker 环境中通过集成测试。
 还将测试从几个最新版本的 Gitea 迁移。
 请在 PR 中附带提交适当的单元测试和集成测试。
 ## 网站文档
 该网站的文档位于 `docs/` 中。如果你改变了文档内容，你可以使用以下测试方法进行持续集成：
 ```bash
 make lint-md
 ```
 ## Visual Studio Code
 `contrib/ide/vscode` 中为 Visual Studio Code 提供了 `launch.json` 和 `tasks.json`。查看
 [`contrib/ide/README.md`](https://github.com/go-gitea/gitea/blob/main/contrib/ide/README.md) 了解更多信息。
 ## Goland
 单击 `/main.go` 中函数 `func main()` 上的 `Run Application` 箭头
 可以快速启动一个可调试的 Gitea 实例。
 `Run/Debug Configuration` 中的 `Output Directory` 必须设置为
 gitea 项目目录（包含 `main.go` 和 `go.mod`），
 否则，启动实例的工作目录是 GoLand 的临时目录
 并防止 Gitea 在开发环境中加载动态资源（例如：模板）。
 要在 GoLand 中使用 SQLite 运行单元测试，请设置 `-tags sqlite,sqlite_unlock_notify`
 在 `运行/调试配置` 的 `Go 工具参数` 中。
 ## 提交 PR
 对更改感到满意后，将它们推送并打开拉取请求。它建议您允许 Gitea Managers 和 Owners 修改您的 PR
 分支，因为我们需要在合并之前将其更新为 main 和/或可能是能够直接帮助解决问题。
 任何 PR 都需要 Gitea 维护者的两次批准，并且需要通过持续集成。看看我们的
 [CONTRIBUTING.md](https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md)
 文档。
 如果您需要更多帮助，请访问 [Discord](https://discord.gg/gitea) #Develop 频道
 并在那里聊天。
 现在，您已准备好 Hacking Gitea。
@@ -1,37 +0,0 @@
 ---
 date: "2023-05-25T17:29:00+08:00"
 slug: "integrations"
 sidebar_position: 65
 aliases:
  - /zh-cn/integrations
 ---
 # 集成
 Gitea 拥有一个出色的第三方集成社区，以及在其他各种项目中的一流支持。
 我们正在[awesome-gitea](https://gitea.com/gitea/awesome-gitea)上整理一个列表来跟踪这些集成！
 如果你正在寻找[CI/CD](https://gitea.com/gitea/awesome-gitea#user-content-devops)，
 一个[SDK](https://gitea.com/gitea/awesome-gitea#user-content-sdk)，
 甚至一些额外的[主题](https://gitea.com/gitea/awesome-gitea#user-content-themes)，
 你可以在[awesome-gitea](https://gitea.com/gitea/awesome-gitea)中找到它们的列表！
 ## 预填新文件名和内容
 如果你想打开一个具有给定名称和内容的新文件，
 你可以使用查询参数来实现：
 ```txt
 GET /{{org}}/{{repo}}/_new/{{filepath}}
    ?filename={{filename}}
    &value={{content}}
 ```
 例如：
 ```txt
 GET https://git.example.com/johndoe/bliss/_new/articles/
    ?filename=hello-world.md
    &value=Hello%2C%20World!
 ```
@@ -1,31 +0,0 @@
 ---
 date: "2023-05-25T17:29:00+08:00"
 slug: "migrations-interfaces"
 sidebar_position: 55
 aliases:
  - /zh-cn/migrations-interfaces
 ---
 # 迁移接口
 完整迁移功能在 Gitea 1.9.0 版本中引入。它定义了两个接口，用于支持从其他 Git 托管平台迁移存储库数据到 Gitea，或者在将来将 Gitea 数据迁移到其他 Git 托管平台。
 目前已实现了从 GitHub、GitLab 和其他 Gitea 实例的迁移。
 首先，Gitea 在包[modules/migration](https://github.com/go-gitea/gitea/tree/main/modules/migration)中定义了一些标准对象。它们是`Repository`、`Milestone`、`Release`、`ReleaseAsset`、`Label`、`Issue`、`Comment`、`PullRequest`、`Reaction`、`Review`、`ReviewComment`。
 ## 下载器接口
 要从新的 Git 托管平台迁移，需要进行两个步骤的更新。
 - 您应该实现一个`Downloader`，用于获取存储库信息。
 - 您应该实现一个`DownloaderFactory`，用于检测 URL 是否匹配，并创建上述的`Downloader`。
  - 您需要在`init()`中通过`RegisterDownloaderFactory`注册`DownloaderFactory`。
 您可以在[downloader.go](https://github.com/go-gitea/gitea/blob/main/modules/migration/downloader.go)中找到这些接口。
 ## 上传器接口
 目前，只实现了`GiteaLocalUploader`，因此我们只能通过此 Uploader 将下载的数据保存到本地的 Gitea 实例。目前不支持其他上传器。
 您可以在[uploader.go](https://github.com/go-gitea/gitea/blob/main/modules/migration/uploader.go)中找到这些接口。
@@ -1,128 +0,0 @@
 ---
 date: "2019-04-19:44:00+01:00"
 slug: "oauth2-provider"
 sidebar_position: 41
 aliases:
  - /zh-cn/oauth2-provider
 ---
 # OAuth2 提供者
 Gitea 支持作为 OAuth2 提供者，允许第三方应用程序在用户同意的情况下访问其资源。此功能自 1.8.0 版起可用。
 ## 端点
 | 端点                     | URL                                 |
 | ------------------------ | ----------------------------------- |
 | OpenID Connect Discovery | `/.well-known/openid-configuration` |
 | Authorization Endpoint   | `/login/oauth/authorize`            |
 | Access Token Endpoint    | `/login/oauth/access_token`         |
 | OpenID Connect UserInfo  | `/login/oauth/userinfo`             |
 | JSON Web Key Set         | `/login/oauth/keys`                 |
 ## 支持的 OAuth2 授权
 目前 Gitea 仅支持 [**Authorization Code Grant**](https://tools.ietf.org/html/rfc6749#section-1.3.1) 标准，并额外支持以下扩展：
 - [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636)
 - [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)
 要将 Authorization Code Grant 作为第三方应用程序，您需要通过在设置中添加一个新的 "应用程序" (`/user/settings/applications`)。
 ## 范围
 Gitea 支持以下令牌范围:
 | 名称                                     | 介绍                                                            |
 | ---------------------------------------- | --------------------------------------------------------------- |
 | **(no scope)**                           | 授予对公共用户配置文件和公共存储库的只读访问权限                |
 | **repo**                                 | 完全控制所有存储库                                              |
 | &nbsp;&nbsp;&nbsp; **repo:status**       | 授予对所有存储库中提交状态的读/写访问权限                       |
 | &nbsp;&nbsp;&nbsp; **public_repo**       | 仅授予对公共存储库的读/写访问权限                               |
 | **admin:repo_hook**                      | 授予对所有存储库的 Hooks 访问权限，该权限已包含在 `repo` 范围中 |
 | &nbsp;&nbsp;&nbsp; **write:repo_hook**   | 授予对存储库 Hooks 的读/写访问权限                              |
 | &nbsp;&nbsp;&nbsp; **read:repo_hook**    | 授予对存储库 Hooks 的只读访问权限                               |
 | **admin:org**                            | 授予对组织设置的完全访问权限                                    |
 | &nbsp;&nbsp;&nbsp; **write:org**         | 授予对组织设置的读/写访问权限                                   |
 | &nbsp;&nbsp;&nbsp; **read:org**          | 授予对组织设置的只读访问权限                                    |
 | **admin:public_key**                     | 授予公钥管理的完全访问权限                                      |
 | &nbsp;&nbsp;&nbsp; **write:public_key**  | 授予对公钥的读/写访问权限                                       |
 | &nbsp;&nbsp;&nbsp; **read:public_key**   | 授予对公钥的只读访问权限                                        |
 | **admin:org_hook**                       | 授予对组织级别 Hooks 的完全访问权限                             |
 | **admin:user_hook**                      | 授予对用户级别 Hooks 的完全访问权限                             |
 | **notification**                         | 授予对通知的完全访问权限                                        |
 | **user**                                 | 授予对用户个人资料信息的完全访问权限                            |
 | &nbsp;&nbsp;&nbsp; **read:user**         | 授予对用户个人资料的读取权限                                    |
 | &nbsp;&nbsp;&nbsp; **user:email**        | 授予对用户电子邮件地址的读取权限                                |
 | &nbsp;&nbsp;&nbsp; **user:follow**       | 授予访问权限以关注/取消关注用户                                 |
 | **delete_repo**                          | 授予删除存储库的权限                                            |
 | **package**                              | 授予对托管包的完全访问权限                                      |
 | &nbsp;&nbsp;&nbsp; **write:package**     | 授予对包的读/写访问权限                                         |
 | &nbsp;&nbsp;&nbsp; **read:package**      | 授予对包的读取权限                                              |
 | &nbsp;&nbsp;&nbsp; **delete:package**    | 授予对包的删除权限                                              |
 | **admin:gpg_key**                        | 授予 GPG 密钥管理的完全访问权限                                 |
 | &nbsp;&nbsp;&nbsp; **write:gpg_key**     | 授予对 GPG 密钥的读/写访问权限                                  |
 | &nbsp;&nbsp;&nbsp; **read:gpg_key**      | 授予对 GPG 密钥的只读访问权限                                   |
 | **admin:application**                    | 授予应用程序管理的完全访问权限                                  |
 | &nbsp;&nbsp;&nbsp; **write:application** | 授予应用程序管理的读/写访问权限                                 |
 | &nbsp;&nbsp;&nbsp; **read:application**  | 授予应用程序管理的读取权限                                      |
 | **sudo**                                 | 允许以站点管理员身份执行操作                                    |
 ## 客户端类型
 Gitea 支持私密和公共客户端类型，[参见 RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1).
 对于公共客户端, 允许在本地回环地址的重定向 URI 中使用任意端口，例如 `http://127.0.0.1/`。根据 [RFC 8252 的建议](https://datatracker.ietf.org/doc/html/rfc8252#section-8.3)，请避免使用 `localhost`。
 ## 示例
 **注意：** 该示例中尚未使用 PKCE。
 1. 将用户重定向到授权端点，以获得他们的访问资源授权:
   ```curl
   https://[YOUR-GITEA-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI& response_type=code&state=STATE
   ```
   在设置中注册应用程序以获得 `CLIENT_ID`。`STATE` 是一个随机字符串，它将在获得用户授权后发送回您的应用程序。`state` 参数是可选的，但您应该使用它来防止 CSRF 攻击。
   ![Authorization Page](/authorize.png)
   用户将会被询问是否授权给您的应用程序。如果他们同意了授权，用户将会被重定向到 `REDIRECT_URL`，例如：
   ```curl
   https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE
   ```
 2. 使用重定向提供的 `code`，您可以请求一个新的应用程序和 Refresh Token。Access Token Endpoint 接受 `application/json` 或 `application/x-www-form-urlencoded` 类型的 POST 请求，例如：
   ```curl
   POST https://[YOUR-GITEA-URL]/login/oauth/access_token
   ```
   ```json
   {
     "client_id": "YOUR_CLIENT_ID",
     "client_secret": "YOUR_CLIENT_SECRET",
     "code": "RETURNED_CODE",
     "grant_type": "authorization_code",
     "redirect_uri": "REDIRECT_URI"
   }
   ```
   返回：
   ```json
   {
     "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjowLCJleHAiOjE1NTUxNzk5MTIsImlhdCI6MTU1NTE3NjMxMn0.0-iFsAwBtxuckA0sNZ6QpBQmywVPz129u75vOM7wPJecw5wqGyBkmstfJHAjEOqrAf_V5Z-1QYeCh_Cz4RiKug",
     "token_type": "bearer",
     "expires_in": 3600,
     "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjoxLCJjbnQiOjEsImV4cCI6MTU1NzgwNDMxMiwiaWF0IjoxNTU1MTc2MzEyfQ.S_HZQBy4q9r5SEzNGNIoFClT43HPNDbUdHH-GYNYYdkRfft6XptJBkUQscZsGxOW975Yk6RbgtGvq1nkEcklOw"
   }
   ```
   `CLIENT_SECRET` 是生成给应用程序的唯一密钥。请注意，该密钥只会在您使用 Gitea 创建/注册应用程序后出现一次。如果您丢失了密钥，您必须在应用程序设置中重新生成密钥。
   `access_token` 请求中的 `REDIRECT_URI` 必须与 `authorize` 请求中的 `REDIRECT_URI` 相符。
 3. 使用 `access_token` 来构造 [API 请求](development/api-usage.md#oauth2-provider) 以读写用户的资源。
@@ -1,9 +0,0 @@
 {
  "label": "帮助",
  "position": 5,
  "link": {
    "type": "generated-index",
    "slug": "/help",
    "title": "帮助"
  }
 }
@@ -1,433 +0,0 @@
 ---
 date: "2023-05-25T16:00:00+02:00"
 slug: "faq"
 sidebar_position: 5
 aliases:
  - /zh-cn/faq
 ---
 # 常见问题
 本页面包含一些常见问题和答案。
 有关更多帮助资源，请查看所有[支持选项](help/support.md)。
 ## 1.x 和 1.x.x 下载之间的区别
 以 1.7.x 版本为例。
 **注意：**此示例也适用于 Docker 镜像！
 在我们的[下载页面](https://dl.gitea.com/gitea/)上，您会看到一个 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`](https://github.com/go-gitea/gitea/tree/release/v1.7)分支的提交上构建的。
 然而，1.7.0 目录是在创建[`v1.7.0`](https://github.com/go-gitea/gitea/releases/tag/v1.7.0)标签时创建的构建。
 这意味着 1.x 的下载会随着提交合并到各自的分支而改变（将其视为每个版本的单独的“main”分支）。
 另一方面，1.x.x 的下载应该永远不会改变。
 ## 如何从 Gogs/GitHub 等迁移到 Gitea
 要从 Gogs 迁移到 Gitea：
 - [Gogs 版本 0.11.46.0418](https://github.com/go-gitea/gitea/issues/4286)
 要从 GitHub 迁移到 Gitea，您可以使用 Gitea 内置的迁移表单。
 为了迁移诸如问题、拉取请求等项目，您需要至少输入您的用户名。
 [Example (requires login)](https://demo.gitea.com/repo/migrate)
 要从 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. 如果使用反向代理，请确保按照[反向代理指南](../administration/reverse-proxies.md)中的正确说明进行设置。
 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 解决此问题，请参阅[反向代理指南](../administration/reverse-proxies.md)。
 ## 自定义模板无法加载或运行错误
 Gitea 的自定义模板必须将其添加到正确的位置，否则 Gitea 将无法找到并使用自定义模板。
 模板的正确路径应该相对于`CustomPath`。
 1. 要找到`CustomPath`，请在站点管理 -> 配置 中查找自定义文件根路径。
   如果找不到，请尝试`echo $GITEA_CUSTOM`。
 2. 如果仍然找不到，默认值可以被[计算](faq.md#Gitea存储文件的位置)
 3. 如果仍然找不到路径，则可以参考[自定义 Gitea](../administration/customizing-gitea.md)页面，将模板添加到正确的位置。
 ## Gitea 是否有"GitHub/GitLab Pages"功能？
 Gitea 不提供内置的 Pages 服务器。您需要一个专用的域名来提供静态页面，以避免 CSRF 安全风险。
 对于简单的用法，您可以使用反向代理来重写和提供 Gitea 的原始文件 URL 中的静态内容。
 还有一些已经可用的第三方服务，比如独立[pages server](https://codeberg.org/Codeberg/pages-server)的或[caddy plugin](https://github.com/42wim/caddy-gitea)，可以提供所需的功能。
 ## 活跃用户与禁止登录用户
 在 Gitea 中，"活跃用户"是指通过电子邮件激活其帐户的用户。
 "禁止登录用户"是指不允许再登录到 Gitea 的用户。
 ## 设置日志记录
 - [官方文档](../administration/logging-config.md)
 ## 什么是 Swagger？
 [Swagger](https://swagger.io/) 是 Gitea 用于其 API 文档的工具。
 所有 Gitea 实例都有内置的 API，无法完全禁用它。
 但是，您可以在 app.ini 的 api 部分将 ENABLE_SWAGGER 设置为 false，以禁用其文档显示。
 有关更多信息，请参阅 Gitea 的[API 文档](development/api-usage.md)。
 您可以在上查看最新的 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](../administration/command-line.md)、[API](development/api-usage.md) 或 Gitea 的管理界面创建新用户。
 ### 仅允许/阻止特定的电子邮件域名
 您可以在`app.ini`中的`[service]`下的配置`EMAIL_DOMAIN_WHITELIST` 或 `EMAIL_DOMAIN_BLOCKLIST`。
 ### 仅允许/阻止特定的 OpenID 提供商
 您可以在`app.ini`的`[openid]`下配置`WHITELISTED_URI`或`BLACKLISTED_URIS`。
 **注意**： 白名单优先，如果白名单非空，则忽略黑名单。
 ### 仅允许发布问题的用户
 目前实现这一点的方法是创建/修改一个具有最大仓库创建限制为 0 的用户。
 ### 受限制的用户
 受限制的用户仅能访问其组织/团队成员和协作所在的内容的子集，而忽略组织/仓库等的公共标志。
 示例用例：一个公司运行一个需要登录的 Gitea 实例。大多数仓库是公开的（所有同事都可以访问/浏览）。
 在某些情况下，某个客户或第三方需要访问特定的仓库，并且只能访问该仓库。通过将此类客户帐户设置为受限制帐户，并使用团队成员身份和/或协作来授予所需的任何访问权限，可以简单地实现这一点，而无需使所有内容都变为私有。
 ### 启用 Fail2ban
 使用 [Fail2Ban](../administration/fail2ban-setup.md) 监视并阻止基于日志模式的自动登录尝试或其他恶意行为。
 ## SSHD vs 内建 SSH
 SSHD 是大多数 Unix 系统上内建的 SSH 服务器。
 Gitea 还提供了自己的 SSH 服务器，用于在 SSHD 不可用时使用。
 ## Gitea 运行缓慢
 导致此问题的最常见原因是加载联合头像。
 您可以通过在`app.ini`中将`ENABLE_FEDERATED_AVATAR`设置为`false`来关闭此功能。
 还有一个可能需要更改的选项是在`app.ini`中将`DISABLE_GRAVATAR`设置为`true`。
 ## 无法创建仓库/文件
 请确保 Gitea 具有足够的权限来写入其主目录和数据目录。
 参见[AppDataPath 和 RepoRootPath](faq.md#Gitea存储文件的位置)
 **适用于 Arch 用户的注意事项：**在撰写本文时，Arch 软件包的 systemd 文件包含了以下行：
 `ReadWritePaths=/etc/gitea/app.ini`
 这将使得 Gitea 无法写入其他路径。
 ## 翻译不正确/如何添加更多翻译
 我们当前的翻译是在我们的[Crowdin 项目](https://crowdin.com/project/gitea)上众包进行的
 无论您想要更改翻译还是添加新的翻译，都需要在 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 [email protected]`
 如果连接成功，您应该会收到以下错误消息：
 ```
 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 命令](../administration/command-line.md#admin)像正常情况下添加用户。
 ## 如何启用密码重置
 没有密码重置的设置。当配置了[邮件服务](../administration/email-setup.md)时，密码重置将自动启用；否则将被禁用。
 ## 如何更改用户的密码
 - 作为管理员，您可以更改任何用户的密码（并可选择强制其在下次登录时更改密码）...
  - 转到您的`站点管理 -> 用户账户`页面并编辑用户。
 - 使用[管理 CLI 命令](../administration/command-line.md#admin)。
  请注意，大多数命令还需要一个[全局标志](../administration/command-line.md#全局选项)来指向正确的配置。
 - 作为**用户**，您可以更改密码...
  - 在您的账户的`设置 -> 账户`页面（此方法**需要**您知道当前密码）。
  - 使用`忘记密码`链接。
  如果`忘记密码/账户恢复`页面被禁用，请联系管理员配置[邮件服务](../administration/email-setup.md)。
 ## 为什么我的 Markdown 显示错误
 在 Gitea 版本 `1.11` 中，我们转换为使用[goldmark](https://github.com/yuin/goldmark)进行 Markdown 渲染，它符合[CommonMark](https://commonmark.org/)标准。
 如果您在版本`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>`来查看。
 要收集日志以进行帮助和问题报告，请参阅[支持选项](help/support.md)。
 ## 初始日志记录
 在 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`](../administration/config-cheat-sheet.md#仓库) 获得类似的权限。
 - 如果上述步骤都正确执行，您应该能够选择要采用的存储库。
  - 如果没有找到存储库，请启用[调试日志记录](../administration/config-cheat-sheet.md#仓库)以检查是否有特定错误。
@@ -1,69 +0,0 @@
 ---
 date: "2017-01-20T15:00:00+08:00"
 slug: "support"
 sidebar_position: 20
 aliases:
  - /zh-cn/seek-help
 ---
 # 支持选项
 - [付费商业支持](https://about.gitea.com/)
 - [Discord](https://discord.gg/Gitea)
 - [论坛](https://forum.gitea.com/)
 - [Matrix](https://matrix.to/#/#gitea-space:matrix.org)
  - 注意：大多数 Matrix 频道都与 Discord 中的对应频道桥接，可能在桥接过程中会出现一定程度的不稳定性。
 - 中文支持
  - [Discourse 中文分类](https://forum.gitea.com/c/5-category/5)
  - QQ 群 328432459
 # Bug 报告
 如果您发现了 Bug，请在 GitHub 上 [创建一个问题](https://github.com/go-gitea/gitea/issues)。
 **注意：** 在请求支持时，可能需要准备以下信息，以便帮助者获得所需的所有信息：
 1. 您的 `app.ini`（将任何敏感数据进行必要的清除）。
 2. 您看到的任何错误消息。
 3. Gitea 日志以及与情况相关的所有其他日志。
   - 收集 `trace` / `debug` 级别的日志更有用（参见下一节）。
   - 在使用 systemd 时，使用 `journalctl --lines 1000 --unit gitea` 收集日志。
   - 在使用 Docker 时，使用 `docker logs --tail 1000 <gitea-container>` 收集日志。
 4. 可重现的步骤，以便他人能够更快速、更容易地重现和理解问题。
   - [demo.gitea.com](https://demo.gitea.com) 可用于重现问题。
 5. 如果遇到慢速/挂起/死锁等问题，请在出现问题时报告堆栈跟踪。
   转到 "Site Admin" -> "Monitoring" -> "Stacktrace" -> "Download diagnosis report"。
 # 高级 Bug 报告提示
 ## 更多日志的配置选项
 默认情况下，日志以 `info` 级别输出到控制台。
 如果您需要设置日志级别和/或从文件中收集日志，
 您只需将以下配置复制到您的 `app.ini` 中（删除所有其他 `[log]` 部分），
 然后您将在 Gitea 的日志目录中找到 `*.log` 文件（默认为 `%(GITEA_WORK_DIR)/log`）。
 ```ini
 ; 要显示所有 SQL 日志，您还可以在 [database] 部分中设置 LOG_SQL=true
 [log]
 LEVEL=debug
 MODE=console,file
 ```
 ## 使用命令行收集堆栈跟踪
 Gitea 可以使用 Golang 的 pprof 处理程序和工具链来收集堆栈跟踪和其他运行时信息。
 如果 Web UI 停止工作，您可以尝试通过命令行收集堆栈跟踪：
 1. 设置 app.ini：
   ```
   [server]
   ENABLE_PPROF = true
   ```
 2. 重新启动 Gitea
 3. 尝试触发 bug，当请求卡住一段时间，使用或浏览器访问：获取堆栈跟踪。
   `curl http://127.0.0.1:6060/debug/pprof/goroutine?debug=1`
@@ -1,75 +0,0 @@
 ---
 date: "2016-11-08T16:00:00+02:00"
 slug: /
 sidebar_position: 10
 ---
 # 关于Gitea
 Gitea 是一个轻量级的 DevOps 平台软件。从开发计划到产品成型的整个软件生命周期，他都能够高效而轻松的帮助团队和开发者。包括 Git 托管、代码审查、团队协作、软件包注册和 CI/CD。它与 GitHub、Bitbucket 和 GitLab 等比较类似。
 Gitea 最初是从 [Gogs](http://gogs.io) 分支而来，几乎所有代码都已更改。对于我们Fork的原因可以看
 [这里](https://blog.gitea.com/welcome-to-gitea/)。
 ## 目标
 Gitea的首要目标是创建一个极易安装，运行非常快速，安装和使用体验良好
 的自建 Git 服务。
 采用Go作为后端语言，只需生成一个可执行程序即可。
 支持 Linux, macOS 和 Windows等多平台，
 支持主流的x86，amd64、
 ARM 和 PowerPC等架构。
 ## 功能特性
 - 代码托管：Gitea⽀持创建和管理仓库、浏览提交历史和代码⽂件、审查和合并代码提交、管理协作者、管理分⽀等。它还⽀持许多常见的Git特性，⽐如标签、Cherry-pick、hook、集成协作⼯具等。
 - 轻量级和快速: Gitea 的设计目标之一就是轻量级和快速响应。它不像一些大型的代码托管平台那样臃肿，因此在性能方面表现出色，适用于资源有限的服务器环境。由于其轻量级设计，Gitea 在资源消耗方面相对较低，可以在资源有限的环境下运行良好。
 - 易于部署和维护: 轻松地部署在各种服务器上，不需要复杂的配置和依赖。这使得个人开发者或小团队可以方便地设置和管理自己的 Git 服务。
 - 安全性: Gitea 注重安全性，提供了用户权限管理、访问控制列表等功能，可以确保代码和数据的安全性。
 - 代码评审：代码评审同时支持 Pull Request workflow 和 AGit workflow。评审⼈可以在线浏览代码，并提交评审意见或问题。 提交者可以接收到评审意见，并在线回 复或修改代码。代码评审可以帮助用户和企业提⾼代码质量。
 - CI/CD: Gitea Actions⽀持 CI/CD 功能，该功能兼容 GitHub Actions，⽤⼾可以采用熟悉的YAML格式编写workflows，也可以重⽤⼤量的已有的 Actions 插件。Actions 插件支持从任意的 Git 网站中下载。
 - 项目管理：Gitea 通过看板和⼯单来跟踪⼀个项⽬的需求，功能和bug。⼯单⽀持分支，标签、⾥程碑、 指派、时间跟踪、到期时间、依赖关系等功能。
 - 制品库: Gitea支持超过 20 种不同种类的公有或私有软件包管理，包括：Cargo, Chef, Composer, Conan, Conda, Container, Helm, Maven, npm, NuGet, Pub, PyPI, RubyGems, Vagrant等
 - 开源社区支持: Gitea 是一个基于 MIT 许可证的开源项目,Gitea 拥有一个活跃的开源社区，能够持续地进行开发和改进，同时也积极接受社区贡献，保持了平台的更新和创新。
 - 多语言支持： Gitea 提供多种语言界面，适应全球范围内的用户，促进了国际化和本地化。
 更多功能特性：详见：https://docs.gitea.com/installation/comparison#general-features
 ## 系统要求
 - 树莓派Pi3功能强大，足以运行 Gitea 来处理小型工作负载。
 - 对于小型团队/项目而言，2 个 CPU 内核和 1GB 内存通常就足够了。
 - 在 UNIX 系统上，Gitea 应使用专用的非 root 系统账户运行。
  - 注意：Gitea 管理 `~/.ssh/authorized_keys` 文件。以普通用户身份运行 Gitea 可能会破坏该用户的登录能力。
 - [Git](https://git-scm.com/) 需要 2.0.0 或更高版本。
  - [Git Large File Storage](https://git-lfs.github.com/) 如果启用，且 Git 版本大于等于 2.1.2，则该选项可用
  - 如果 Git 版本大于等于 2.18，将自动启用 Git 提交历史图形化展示功能
 ## 浏览器支持
 - Last 2 versions of Chrome, Firefox, Safari and Edge
 - Firefox ESR
 ## 技术栈
 - Web框架： [Chi](http://github.com/go-chi/chi)
 - ORM: [XORM](https://xorm.io)
 - UI 框架：
  - [jQuery](https://jquery.com)
  - [Fomantic UI](https://fomantic-ui.com)
  - [Vue3](https://vuejs.org)
  - 更多组件参见 package.json
 - 编辑器：
  - [CodeMirror](https://codemirror.net)
  - [EasyMDE](https://github.com/Ionaru/easy-markdown-editor)
  - [Monaco Editor](https://microsoft.github.io/monaco-editor)
 - 数据库驱动：
  - [github.com/go-sql-driver/mysql](https://github.com/go-sql-driver/mysql)
  - [github.com/lib/pq](https://github.com/lib/pq)
  - [github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3)
  - [github.com/denisenkom/go-mssqldb](https://github.com/denisenkom/go-mssqldb)
 ## 集成支持
 请访问 [Awesome Gitea](https://gitea.com/gitea/awesome-gitea/) 获得更多的第三方集成支持
@@ -1,9 +0,0 @@
 {
  "label": "安装",
  "position": 10,
  "link": {
    "type": "generated-index",
    "slug": "/installation",
    "title": "安装"
  }
 }
@@ -1,140 +0,0 @@
 ---
 date: "2019-02-14T11:51:04+08:00"
 slug: "comparison"
 sidebar_position: 5
 aliases:
  - /zh-cn/comparison
 ---
 # 对比 Gitea 与其它 Git 托管工具
 这里列出了 Gitea 与其它一些 Git 托管工具之间的异同，以便确认 Gitea 是否能够满足您的需求。
 请注意，此列表中的某些表项可能已经过时，因为我们并没有定期检查其它产品的功能是否有所更改。你可以前往 [Github issue](https://github.com/go-gitea/gitea/issues) 来帮助我们更新过时的内容，感谢！
 _表格中的符号含义:_
 - _✓ - 支持_
 - _⁄ - 部分支持_
 - _✘ - 不支持_
 - _⚙️ - 由第三方服务或插件支持_
 #### 主要特性
 | 特性                             | Gitea                                               | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket      | RhodeCode CE |
 | -------------------------------- | --------------------------------------------------- | ---- | --------- | --------- | --------- | -------------- | ------------ |
 | 开源免费                         | ✓                                                   | ✓    | ✘         | ✓         | ✘         | ✘              | ✓            |
 | 低资源开销 (RAM/CPU)             | ✓                                                   | ✓    | ✘         | ✘         | ✘         | ✘              | ✘            |
 | 支持多种数据库                   | ✓                                                   | ✓    | ✘         | ⁄         | ⁄         | ✓              | ✓            |
 | 支持多种操作系统                 | ✓                                                   | ✓    | ✘         | ✘         | ✘         | ✘              | ✓            |
 | 升级简便                         | ✓                                                   | ✓    | ✘         | ✓         | ✓         | ✘              | ✓            |
 | 可观测性                         | **✘**                                               | ✘    | ✓         | ✓         | ✓         | ✓              | ?            |
 | 支持第三方渲染工具               | ✓                                                   | ✘    | ✘         | ✘         | ✘         | ✓              | ?            |
 | WebAuthn (2FA)                   | ✓                                                   | ✘    | ✓         | ✓         | ✓         | ✓              | ?            |
 | 扩展 API                         | ✓                                                   | ✓    | ✓         | ✓         | ✓         | ✓              | ✓            |
 | 内置软件包/容器注册中心          | ✓                                                   | ✘    | ✓         | ✓         | ✓         | ✘              | ✘            |
 | 同步提交到外部仓库 (push mirror) | ✓                                                   | ✓    | ✘         | ✓         | ✓         | ✘              | ✓            |
 | 同步外部仓库的提交 (pull mirror) | ✓                                                   | ✘    | ✘         | ✓         | ✓         | ✘              | ?            |
 | 浅色和深色主题                   | ✓                                                   | ✘    | ✓         | ✓         | ✓         | ✘              | ?            |
 | 自定义主题支持                   | ✓                                                   | ✓    | ✘         | ✘         | ✘         | ✓              | ✘            |
 | 支持 Markdown                    | ✓                                                   | ✓    | ✓         | ✓         | ✓         | ✓              | ✓            |
 | 支持 CSV                         | ✓                                                   | ✘    | ✓         | ✘         | ✘         | ✓              | ?            |
 | Git 驱动的静态 pages             | [⚙️][gitea-pages-server], [⚙️][gitea-caddy-plugin]  | ✘    | ✓         | ✓         | ✓         | ✘              | ✘            |
 | Git 驱动的集成化 wiki            | ✓                                                   | ✓    | ✓         | ✓         | ✓         | ✓ (cloud only) | ✘            |
 | 部署令牌                         | ✓                                                   | ✓    | ✓         | ✓         | ✓         | ✓              | ✓            |
 | 仓库写权限令牌                   | ✓                                                   | ✘    | ✓         | ✓         | ✓         | ✓              | ✓            |
 | RSS Feeds                        | ✓                                                   | ✘    | ✓         | ✘         | ✘         | ✘              | ✘            |
 | 内置 CI/CD                       | ✓                                                   | ✘    | ✓         | ✓         | ✓         | ✘              | ✘            |
 | 子组织：组织内的组织             | [✘](https://github.com/go-gitea/gitea/issues/1872)  | ✘    | ✘         | ✓         | ✓         | ✘              | ✓            |
 | 多实例交互                       | [/](https://github.com/go-gitea/gitea/issues/18240) | ✘    | ✘         | ✘         | ✘         | ✘              | ✘            |
 | Markdown 绘图                    | ✓                                                   | ✘    | ✓         | ✓         | ✓         | ✘              | ✘            |
 | Markdown 数学公式                | ✓                                                   | ✘    | ✓         | ✓         | ✓         | ✘              | ✘            |
 #### 代码管理
 | 特性                 | Gitea                                               | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE |
 | -------------------- | --------------------------------------------------- | ---- | --------- | --------- | --------- | --------- | ------------ |
 | 仓库主题描述         | ✓                                                   | ✘    | ✓         | ✓         | ✓         | ✘         | ✘            |
 | 仓库内代码搜索       | ✓                                                   | ✘    | ✓         | ✓         | ✓         | ✓         | ✓            |
 | 全局代码搜索         | ✓                                                   | ✘    | ✓         | ✘         | ✓         | ✓         | ✓            |
 | Git LFS 2.0          | ✓                                                   | ✘    | ✓         | ✓         | ✓         | ✓         | ✓            |
 | 组织里程碑           | [✘](https://github.com/go-gitea/gitea/issues/14622) | ✘    | ✘         | ✓         | ✓         | ✘         | ✘            |
 | 细粒度用户角色       | ✓                                                   | ✘    | ✘         | ✓         | ✓         | ✘         | ✘            |
 | 提交人的身份验证     | ⁄                                                   | ✘    | ?         | ✓         | ✓         | ✓         | ✘            |
 | GPG 签名的提交       | ✓                                                   | ✘    | ✓         | ✓         | ✓         | ✓         | ✓            |
 | SSH 签名的提交       | ✓                                                   | ✘    | ✓         | ✓         | ✓         | ?         | ?            |
 | 拒绝未通过验证的提交 | ✓                                                   | ✘    | ✓         | ✓         | ✓         | ✓         | ✓            |
 | 外部仓库迁移         | ✓                                                   | ✘    | ✓         | ✓         | ✓         | ✓         | ✓            |
 | 仓库活跃度页面       | ✓                                                   | ✘    | ✓         | ✓         | ✓         | ✓         | ✓            |
 | 分支管理             | ✓                                                   | ✘    | ✓         | ✓         | ✓         | ✓         | ✓            |
 | 建立新分支           | ✓                                                   | ✘    | ✓         | ✓         | ✓         | ✘         | ✘            |
 | 在线代码编辑         | ✓                                                   | ✓    | ✓         | ✓         | ✓         | ✓         | ✓            |
 | 提交的统计图表       | ✓                                                   | ✘    | ✓         | ✓         | ✓         | ✓         | ✓            |
 | 模板仓库             | ✓                                                   | ✘    | ✓         | ✘         | ✓         | ✓         | ✘            |
 | Git Blame            | ✓                                                   | ✘    | ✓         | ✓         | ✓         | ✓         | ✘            |
 | 可视化镜像变化       | ✓                                                   | ✘    | ✓         | ?         | ?         | ?         | ?            |
 #### 工单管理
 | 特性                | Gitea                                              | Gogs                                          | GitHub EE | GitLab CE                                                               | GitLab EE | BitBucket      | RhodeCode CE |
 | ------------------- | -------------------------------------------------- | --------------------------------------------- | --------- | ----------------------------------------------------------------------- | --------- | -------------- | ------------ |
 | 工单跟踪            | ✓                                                  | ✓                                             | ✓         | ✓                                                                       | ✓         | ✓ (cloud only) | ✘            |
 | 工单模板            | ✓                                                  | ✓                                             | ✓         | ✓                                                                       | ✓         | ✘              | ✘            |
 | 标签                | ✓                                                  | ✓                                             | ✓         | ✓                                                                       | ✓         | ✘              | ✘            |
 | 时间跟踪            | ✓                                                  | ✘                                             | ✓         | ✓                                                                       | ✓         | ✘              | ✘            |
 | 支持多个负责人      | ✓                                                  | ✘                                             | ✓         | ✘                                                                       | ✓         | ✘              | ✘            |
 | 关联的工单          | ✘                                                  | ✘                                             | ⁄         | [✓](https://docs.gitlab.com/ce/user/project/issues/related_issues.html) | ✓         | ✘              | ✘            |
 | 私密工单            | [✘](https://github.com/go-gitea/gitea/issues/3217) | ✘                                             | ✘         | ✓                                                                       | ✓         | ✘              | ✘            |
 | 评论反馈            | ✓                                                  | ✘                                             | ✓         | ✓                                                                       | ✓         | ✘              | ✘            |
 | 锁定讨论            | ✓                                                  | ✘                                             | ✓         | ✓                                                                       | ✓         | ✘              | ✘            |
 | 工单批处理          | ✓                                                  | ✘                                             | ✓         | ✓                                                                       | ✓         | ✘              | ✘            |
 | 工单看板            | [✓](https://github.com/go-gitea/gitea/pull/8346)   | ✘                                             | ✘         | ✓                                                                       | ✓         | ✘              | ✘            |
 | 从工单创建分支      | ✘                                                  | ✘                                             | ✘         | ✓                                                                       | ✓         | ✘              | ✘            |
 | 从评论创建工单      | ✓                                                  | ✘                                             | ✓         | ✓                                                                       | ✓         | ✘              | ✘            |
 | 工单搜索            | ✓                                                  | ✘                                             | ✓         | ✓                                                                       | ✓         | ✓              | ✘            |
 | 工单全局搜索        | [✘](https://github.com/go-gitea/gitea/issues/2434) | ✘                                             | ✓         | ✓                                                                       | ✓         | ✓              | ✘            |
 | 工单依赖关系        | ✓                                                  | ✘                                             | ✘         | ✘                                                                       | ✘         | ✘              | ✘            |
 | 通过 Email 创建工单 | [✘](https://github.com/go-gitea/gitea/issues/6226) | [✘](https://github.com/gogs/gogs/issues/2602) | ✘         | ✓                                                                       | ✓         | ✓              | ✘            |
 | 服务台              | [✘](https://github.com/go-gitea/gitea/issues/6219) | ✘                                             | ✘         | [✓](https://gitlab.com/groups/gitlab-org/-/epics/3103)                  | ✓         | ✘              | ✘            |
 #### Pull/Merge requests
 | 特性                                 | Gitea                                              | Gogs | GitHub EE | GitLab CE                                                                         | GitLab EE | BitBucket                                                                | RhodeCode CE |
 | ------------------------------------ | -------------------------------------------------- | ---- | --------- | --------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------ | ------------ |
 | Pull/Merge requests                  | ✓                                                  | ✓    | ✓         | ✓                                                                                 | ✓         | ✓                                                                        | ✓            |
 | Squash merging                       | ✓                                                  | ✘    | ✓         | [✓](https://docs.gitlab.com/ce/user/project/merge_requests/squash_and_merge.html) | ✓         | ✓                                                                        | ✓            |
 | Rebase merging                       | ✓                                                  | ✓    | ✓         | ✘                                                                                 | ⁄         | ✘                                                                        | ✓            |
 | 评论 Pull/Merge request 中的某行代码 | ✓                                                  | ✘    | ✓         | ✓                                                                                 | ✓         | ✓                                                                        | ✓            |
 | 指定 Pull/Merge request 的审核人     | ✓                                                  | ✘    | ⁄         | ✓                                                                                 | ✓         | ✓                                                                        | ✓            |
 | 解决 Merge 冲突                      | [✘](https://github.com/go-gitea/gitea/issues/5158) | ✘    | ✓         | ✓                                                                                 | ✓         | ✓                                                                        | ✘            |
 | 限制某些用户的 push 和 merge 权限    | ✓                                                  | ✘    | ✓         | ⁄                                                                                 | ✓         | ✓                                                                        | ✓            |
 | 回退某些 commits 或 merge request    | [✓](https://github.com/go-gitea/gitea/issues/5158) | ✘    | ✓         | ✓                                                                                 | ✓         | ✓                                                                        | ✘            |
 | Pull/Merge requests 模板             | ✓                                                  | ✓    | ✓         | ✓                                                                                 | ✓         | ✘                                                                        | ✘            |
 | 查看 Cherry-picking 的更改           | [✓](https://github.com/go-gitea/gitea/issues/5158) | ✘    | ✘         | ✓                                                                                 | ✓         | ✘                                                                        | ✘            |
 | 下载 Patch                           | ✓                                                  | ✘    | ✓         | ✓                                                                                 | ✓         | [/](https://jira.atlassian.com/plugins/servlet/mobile#issue/BCLOUD-8323) | ✘            |
 | Merge queues                         | ✘                                                  | ✘    | ✓         | ✘                                                                                 | ✓         | ✘                                                                        | ✘            |
 #### 第三方集成
 | 特性                       | Gitea                                              | Gogs                                          | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE |
 | -------------------------- | -------------------------------------------------- | --------------------------------------------- | --------- | --------- | --------- | --------- | ------------ |
 | 支持 Webhook               | ✓                                                  | ✓                                             | ✓         | ✓         | ✓         | ✓         | ✓            |
 | 自定义 Git 钩子            | ✓                                                  | ✓                                             | ✓         | ✓         | ✓         | ✓         | ✓            |
 | 集成 AD / LDAP             | ✓                                                  | ✓                                             | ✓         | ✓         | ✓         | ✓         | ✓            |
 | 支持多个 LDAP / AD 服务    | ✓                                                  | ✓                                             | ✘         | ✘         | ✓         | ✓         | ✓            |
 | LDAP 用户同步              | ✓                                                  | ✘                                             | ✓         | ✓         | ✓         | ✓         | ✓            |
 | SAML 2.0 service provider  | [✘](https://github.com/go-gitea/gitea/issues/5512) | [✘](https://github.com/gogs/gogs/issues/1221) | ✓         | ✓         | ✓         | ✓         | ✘            |
 | 支持 OpenId 连接           | ✓                                                  | ✘                                             | ✓         | ✓         | ✓         | ?         | ✘            |
 | 集成 OAuth 2.0（外部授权） | ✓                                                  | ✘                                             | ⁄         | ✓         | ✓         | ?         | ✓            |
 | 作为 OAuth 2.0 provider    | [✓](https://github.com/go-gitea/gitea/pull/5378)   | ✘                                             | ✓         | ✓         | ✓         | ✓         | ✘            |
 | 二次验证 (2FA)             | ✓                                                  | ✓                                             | ✓         | ✓         | ✓         | ✓         | ✘            |
 | 集成 Mattermost/Slack      | ✓                                                  | ✓                                             | ⁄         | ✓         | ✓         | ⁄         | ✓            |
 | 集成 Discord               | ✓                                                  | ✓                                             | ✓         | ✓         | ✓         | ✘         | ✘            |
 | 集成 Microsoft Teams       | ✓                                                  | ✘                                             | ✓         | ✓         | ✓         | ✓         | ✘            |
 | 显示外部 CI/CD 的状态      | ✓                                                  | ✘                                             | ✓         | ✓         | ✓         | ✓         | ✓            |
 [gitea-caddy-plugin]: https://github.com/42wim/caddy-gitea
 [gitea-pages-server]: https://codeberg.org/Codeberg/pages-server
Author	SHA1	Message	Date
Lunny Xiao	d39c6d0cd6	Merge branch 'main' into audit	2026-09-19 00:12:43 +00:00
Lunny Xiao	0c1071b3a6	Merge branch 'main' into audit	2026-09-19 00:04:45 +00:00
Lunny Xiao	2b1ddd1d44	Merge branch 'main' into audit	2026-09-18 03:37:34 +00:00
silverwindandClaude	1dd914792d	Correct audit logging actors, warning and coverage The system actor names did not match what Gitea records, the disabled warning only shows on the admin page, and the recorded/not recorded lists overstated login and issue edit coverage while missing user status changes. Co-Authored-By: Claude (Opus 5) <[email protected]>	2026-09-18 03:14:54 +02:00
Lunny Xiao	240a2840a4	Merge branch 'main' into audit	2026-09-17 20:22:15 +00:00
bircni	fa7c65e2dd	Merge branch 'main' into audit	2026-09-13 07:30:18 +00:00
bircni	a018c73100	docs: Document audit logging	2026-09-12 13:21:33 +02:00