Mirrors/gitea
0
0
Fork 0
mirror of https://github.com/go-gitea/gitea.git synced 2026-06-16 10:06:11 +02:00
Code Issues Activity

Merge branch 'limit-repo-size' of https://github.com/DmitryFrolovTri/gitea into limit-repo-size

Browse Source
This commit is contained in:
truecode112 2023-05-26 16:53:25 +03:00
commit ccc564a180
246 changed files with 8807 additions and 1303 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.air.toml
View File

@ -2,7 +2,7 @@ root = "."
tmp_dir = ".air"
[build]
cmd = "make backend"
cmd = "make --no-print-directory backend"
bin = "gitea"
delay = 1000
include_ext = ["go", "tmpl"]

15
.github/file-filters.yml vendored Normal file
View File

@ -0,0 +1,15 @@
docs: &docs
- "**/*.md"
- "docs/**"
backend: &backend
- "**/*.go"
- "**/*.tmpl"
- "go.mod"
- "go.sum"
frontend: &frontend
- "**/*.js"
- "web_src/**"
- "package.json"
- "package-lock.json"

32
.github/workflows/files-changed.yml vendored Normal file
View File

@ -0,0 +1,32 @@
name: files changed
on:
workflow_call:
outputs:
docs:
description: "whether docs files changed"
value: ${{ jobs.files-changed.outputs.docs }}
backend:
description: "whether backend files changed"
value: ${{ jobs.files-changed.outputs.backend }}
frontend:
description: "whether frontend files changed"
value: ${{ jobs.files-changed.outputs.frontend }}
jobs:
files-changed:
name: detect which files changed
runs-on: ubuntu-latest
timeout-minutes: 3
# Map a step output to a job output
outputs:
docs: ${{ steps.changes.outputs.docs }}
backend: ${{ steps.changes.outputs.backend }}
frontend: ${{ steps.changes.outputs.frontend }}
steps:
- uses: actions/checkout@v3
- name: Check for backend file changes
uses: dorny/paths-filter@v2
id: changes
with:
filters: .github/file-filters.yml

9
.github/workflows/pull-compliance-docs.yml vendored
View File

@ -2,16 +2,18 @@ name: compliance-docs
on:
pull_request:
paths:
- "docs/**"
- "*.md"
concurrency:
group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
cancel-in-progress: true
jobs:
files-changed:
uses: ./.github/workflows/files-changed.yml
compliance-docs:
if: needs.files-changed.outputs.docs == 'true'
needs: files-changed
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
@ -20,3 +22,4 @@ jobs:
node-version: 20
- run: make deps-frontend
- run: make lint-md
- run: make docs # test if build could succeed

43
.github/workflows/pull-compliance-docsignore.yml vendored
View File

@ -1,43 +0,0 @@
name: compliance
on:
pull_request:
paths:
- "docs/**"
- "*.md"
jobs:
compliance-docs:
runs-on: ubuntu-latest
steps:
- run: echo "No build required"
lint-backend:
runs-on: ubuntu-latest
steps:
- run: echo "No build required"
lint-go-windows:
runs-on: ubuntu-latest
steps:
- run: echo "No build required"
lint-go-gogit:
runs-on: ubuntu-latest
steps:
- run: echo "No build required"
checks-backend:
runs-on: ubuntu-latest
steps:
- run: echo "No build required"
frontend:
runs-on: ubuntu-latest
steps:
- run: echo "No build required"
backend:
runs-on: ubuntu-latest
steps:
- run: echo "No build required"

18
.github/workflows/pull-compliance.yml vendored
View File

@ -2,16 +2,18 @@ name: compliance
on:
pull_request:
paths-ignore:
- "docs/**"
- "*.md"
concurrency:
group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
cancel-in-progress: true
jobs:
files-changed:
uses: ./.github/workflows/files-changed.yml
lint-backend:
if: needs.files-changed.outputs.backend == 'true'
needs: files-changed
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
@ -24,6 +26,8 @@ jobs:
env:
TAGS: bindata sqlite sqlite_unlock_notify
lint-go-windows:
if: needs.files-changed.outputs.backend == 'true'
needs: files-changed
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
@ -38,6 +42,8 @@ jobs:
GOOS: windows
GOARCH: amd64
lint-go-gogit:
if: needs.files-changed.outputs.backend == 'true'
needs: files-changed
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
@ -50,6 +56,8 @@ jobs:
env:
TAGS: bindata gogit sqlite sqlite_unlock_notify
checks-backend:
if: needs.files-changed.outputs.backend == 'true'
needs: files-changed
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
@ -60,6 +68,8 @@ jobs:
- run: make deps-backend deps-tools
- run: make --always-make checks-backend # ensure the "go-licenses" make target runs
frontend:
if: needs.files-changed.outputs.frontend == 'true'
needs: files-changed
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
@ -70,6 +80,8 @@ jobs:
- run: make lint-frontend
- run: make checks-frontend
backend:
if: needs.files-changed.outputs.backend == 'true'
needs: files-changed
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3

38
.github/workflows/pull-db-tests-docsignore.yml vendored
View File

@ -1,38 +0,0 @@
name: db-tests
on:
pull_request:
paths:
- "docs/**"
- "*.md"
jobs:
test-pgsql:
runs-on: ubuntu-latest
steps:
- run: echo "No build required"
test-sqlite:
runs-on: ubuntu-latest
steps:
- run: echo "No build required"
test-unit:
runs-on: ubuntu-latest
steps:
- run: echo "No build required"
test-mysql5:
runs-on: ubuntu-latest
steps:
- run: echo "No build required"
test-mysql8:
runs-on: ubuntu-latest
steps:
- run: echo "No build required"
test-mssql:
runs-on: ubuntu-latest
steps:
- run: echo "No build required"

18
.github/workflows/pull-db-tests.yml vendored
View File

@ -2,16 +2,18 @@ name: db-tests
on:
pull_request:
paths-ignore:
- "docs/**"
- "*.md"
concurrency:
group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
cancel-in-progress: true
jobs:
files-changed:
uses: ./.github/workflows/files-changed.yml
test-pgsql:
if: needs.files-changed.outputs.backend == 'true' || needs.files-changed.outputs.frontend == 'true'
needs: files-changed
runs-on: ubuntu-latest
services:
pgsql:
@ -56,6 +58,8 @@ jobs:
USE_REPO_TEST_DIR: 1
test-sqlite:
if: needs.files-changed.outputs.backend == 'true' || needs.files-changed.outputs.frontend == 'true'
needs: files-changed
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
@ -75,6 +79,8 @@ jobs:
USE_REPO_TEST_DIR: 1
test-unit:
if: needs.files-changed.outputs.backend == 'true'
needs: files-changed
runs-on: ubuntu-latest
services:
mysql:
@ -138,6 +144,8 @@ jobs:
GITHUB_READ_TOKEN: ${{ secrets.GITHUB_READ_TOKEN }}
test-mysql5:
if: needs.files-changed.outputs.backend == 'true' || needs.files-changed.outputs.frontend == 'true'
needs: files-changed
runs-on: ubuntu-latest
services:
mysql:
@ -180,6 +188,8 @@ jobs:
TEST_INDEXER_CODE_ES_URL: "http://elastic:changeme@elasticsearch:9200"
test-mysql8:
if: needs.files-changed.outputs.backend == 'true' || needs.files-changed.outputs.frontend == 'true'
needs: files-changed
runs-on: ubuntu-latest
services:
mysql8:
@ -207,6 +217,8 @@ jobs:
USE_REPO_TEST_DIR: 1
test-mssql:
if: needs.files-changed.outputs.backend == 'true' || needs.files-changed.outputs.frontend == 'true'
needs: files-changed
runs-on: ubuntu-latest
services:
mssql:

13
.github/workflows/pull-docker-dryrun-docsignore.yml vendored
View File

@ -1,13 +0,0 @@
name: docker-dryrun
on:
pull_request:
paths:
- "docs/**"
- "*.md"
jobs:
docker-dryrun:
runs-on: ubuntu-latest
steps:
- run: echo "No build required"

8
.github/workflows/pull-docker-dryrun.yml vendored
View File

@ -2,16 +2,18 @@ name: docker-dryrun
on:
pull_request:
paths-ignore:
- "docs/**"
- "*.md"
concurrency:
group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
cancel-in-progress: true
jobs:
files-changed:
uses: ./.github/workflows/files-changed.yml
docker-dryrun:
if: needs.files-changed.outputs.backend == 'true' || needs.files-changed.outputs.frontend == 'true'
needs: files-changed
runs-on: ubuntu-latest
steps:
- uses: docker/setup-buildx-action@v2

13
.github/workflows/pull-e2e-tests-docsignore.yml vendored
View File

@ -1,13 +0,0 @@
name: e2e-tests
on:
pull_request:
paths:
- "docs/**"
- "*.md"
jobs:
test-e2e:
runs-on: ubuntu-latest
steps:
- run: echo "No build required"

8
.github/workflows/pull-e2e-tests.yml vendored
View File

@ -2,16 +2,18 @@ name: e2e-tests
on:
pull_request:
paths-ignore:
- "docs/**"
- "*.md"
concurrency:
group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
cancel-in-progress: true
jobs:
files-changed:
uses: ./.github/workflows/files-changed.yml
test-e2e:
if: needs.files-changed.outputs.backend == 'true' || needs.files-changed.outputs.frontend == 'true'
needs: files-changed
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3

1
MAINTAINERS
View File

@ -51,3 +51,4 @@ Dong Ge <gedong_1994@163.com> (@sillyguodong)
Xinyi Gong <hestergong@gmail.com> (@HesterG)
wxiaoguang <wxiaoguang@gmail.com> (@wxiaoguang)
Gary Moon <gary@garymoon.net> (@garymoon)
Philip Peterson <philip.c.peterson@gmail.com> (@philip-peterson)

11
Makefile
View File

@ -35,6 +35,7 @@ SWAGGER_PACKAGE ?= github.com/go-swagger/go-swagger/cmd/swagger@v0.30.4
XGO_PACKAGE ?= src.techknowlogick.com/xgo@latest
GO_LICENSES_PACKAGE ?= github.com/google/go-licenses@v1.6.0
GOVULNCHECK_PACKAGE ?= golang.org/x/vuln/cmd/govulncheck@latest
ACTIONLINT_PACKAGE ?= github.com/rhysd/actionlint/cmd/actionlint@latest
DOCKER_IMAGE ?= gitea/gitea
DOCKER_TAG ?= latest
@ -199,6 +200,7 @@ help:
@echo " - deps-tools install tool dependencies"
@echo " - lint lint everything"
@echo " - lint-fix lint everything and fix issues"
@echo " - lint-actions lint action workflow files"
@echo " - lint-frontend lint frontend files"
@echo " - lint-frontend-fix lint frontend files and fix issues"
@echo " - lint-backend lint backend files"
@ -411,13 +413,17 @@ lint-go-vet:
lint-editorconfig:
$(GO) run $(EDITORCONFIG_CHECKER_PACKAGE) templates .github/workflows
.PHONY: lint-actions
lint-actions:
$(GO) run $(ACTIONLINT_PACKAGE)
.PHONY: watch
watch:
bash build/watch.sh
@bash build/watch.sh
.PHONY: watch-frontend
watch-frontend: node-check node_modules
rm -rf $(WEBPACK_DEST_ENTRIES)
@rm -rf $(WEBPACK_DEST_ENTRIES)
NODE_ENV=development npx webpack --watch --progress
.PHONY: watch-backend
@ -908,6 +914,7 @@ deps-tools:
$(GO) install $(XGO_PACKAGE)
$(GO) install $(GO_LICENSES_PACKAGE)
$(GO) install $(GOVULNCHECK_PACKAGE)
$(GO) install $(ACTIONLINT_PACKAGE)
node_modules: package-lock.json
npm install --no-save

4
build/watch.sh
View File

@ -1,8 +1,8 @@
#!/bin/bash
set -euo pipefail
make watch-frontend &
make watch-backend &
make --no-print-directory watch-frontend &
make --no-print-directory watch-backend &
trap 'kill $(jobs -p)' EXIT
wait

18
cmd/hook.go
View File

@ -201,7 +201,7 @@ Gitea or set your environment appropriately.`, "")
oldCommitIDs := make([]string, hookBatchSize)
newCommitIDs := make([]string, hookBatchSize)
refFullNames := make([]string, hookBatchSize)
refFullNames := make([]git.RefName, hookBatchSize)
count := 0
total := 0
lastline := 0
@ -236,14 +236,14 @@ Gitea or set your environment appropriately.`, "")
oldCommitID := string(fields[0])
newCommitID := string(fields[1])
refFullName := string(fields[2])
refFullName := git.RefName(fields[2])
total++
lastline++
// If the ref is a branch or tag, check if it's protected
// if supportProcReceive all ref should be checked because
// permission check was delayed
if supportProcReceive || strings.HasPrefix(refFullName, git.BranchPrefix) || strings.HasPrefix(refFullName, git.TagPrefix) {
if supportProcReceive || refFullName.IsBranch() || refFullName.IsTag() {
oldCommitIDs[count] = oldCommitID
newCommitIDs[count] = newCommitID
refFullNames[count] = refFullName
@ -351,7 +351,7 @@ Gitea or set your environment appropriately.`, "")
}
oldCommitIDs := make([]string, hookBatchSize)
newCommitIDs := make([]string, hookBatchSize)
refFullNames := make([]string, hookBatchSize)
refFullNames := make([]git.RefName, hookBatchSize)
count := 0
total := 0
wasEmpty := false
@ -373,7 +373,7 @@ Gitea or set your environment appropriately.`, "")
fmt.Fprintf(out, ".")
oldCommitIDs[count] = string(fields[0])
newCommitIDs[count] = string(fields[1])
refFullNames[count] = string(fields[2])
refFullNames[count] = git.RefName(fields[2])
if refFullNames[count] == git.BranchPrefix+"master" && newCommitIDs[count] != git.EmptySHA && count == total {
masterPushed = true
}
@ -575,7 +575,7 @@ Gitea or set your environment appropriately.`, "")
}
hookOptions.OldCommitIDs = make([]string, 0, hookBatchSize)
hookOptions.NewCommitIDs = make([]string, 0, hookBatchSize)
hookOptions.RefFullNames = make([]string, 0, hookBatchSize)
hookOptions.RefFullNames = make([]git.RefName, 0, hookBatchSize)
for {
// note: pktLineTypeUnknow means pktLineTypeFlush and pktLineTypeData all allowed
@ -593,7 +593,7 @@ Gitea or set your environment appropriately.`, "")
}
hookOptions.OldCommitIDs = append(hookOptions.OldCommitIDs, t[0])
hookOptions.NewCommitIDs = append(hookOptions.NewCommitIDs, t[1])
hookOptions.RefFullNames = append(hookOptions.RefFullNames, t[2])
hookOptions.RefFullNames = append(hookOptions.RefFullNames, git.RefName(t[2]))
}
hookOptions.GitPushOptions = make(map[string]string)
@ -640,7 +640,7 @@ Gitea or set your environment appropriately.`, "")
for _, rs := range resp.Results {
if len(rs.Err) > 0 {
err = writeDataPktLine(ctx, os.Stdout, []byte("ng "+rs.OriginalRef+" "+rs.Err))
err = writeDataPktLine(ctx, os.Stdout, []byte("ng "+rs.OriginalRef.String()+" "+rs.Err))
if err != nil {
return err
}
@ -648,7 +648,7 @@ Gitea or set your environment appropriately.`, "")
}
if rs.IsNotMatched {
err = writeDataPktLine(ctx, os.Stdout, []byte("ok "+rs.OriginalRef))
err = writeDataPktLine(ctx, os.Stdout, []byte("ok "+rs.OriginalRef.String()))
if err != nil {
return err
}

12
custom/conf/app.example.ini
View File

@ -49,8 +49,9 @@ APP_NAME = ; Gitea: Git with a cup of tea
;; RUN_USER will automatically detect the current user - but you can set it here change it if you run locally
RUN_USER = ; git
;;
;; Application run mode, affects performance and debugging. Either "dev", "prod" or "test", default is "prod"
RUN_MODE = ; prod
;; Application run mode, affects performance and debugging: "dev" or "prod", default is "prod"
;; Mode "dev" makes Gitea easier to develop and debug, values other than "dev" are treated as "prod" which is for production use.
;RUN_MODE = prod
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@ -1056,6 +1057,9 @@ LEVEL = Info
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; List of reasons why a Pull Request or Issue can be locked
;LOCK_REASONS = Too heated,Off-topic,Resolved,Spam
;; Maximum number of pinned Issues
;; Set to 0 to disable pinning Issues
;MAX_PINNED = 3
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@ -1370,6 +1374,10 @@ LEVEL = Info
;; repo indexer by default disabled, since it uses a lot of disk space
;REPO_INDEXER_ENABLED = false
;;
;; repo indexer units, the items to index, could be `sources`, `forks`, `mirrors`, `templates` or any combination of them separated by a comma.
;; If empty then it defaults to `sources` only, as if you'd like to disable fully please see REPO_INDEXER_ENABLED.
;REPO_INDEXER_REPO_TYPES = sources,forks,mirrors,templates
;;
;; Code search engine type, could be `bleve` or `elasticsearch`.
;REPO_INDEXER_TYPE = bleve
;;

14
docs/content/doc/administration/config-cheat-sheet.en-us.md
View File

@ -73,7 +73,7 @@ In addition there is _`StaticRootPath`_ which can be set as a built-in at build
- `RUN_USER`: **_current OS username_/`$USER`/`$USERNAME` e.g. git**: The user Gitea will run as.
This should be a dedicated system (non-user) account. Setting this incorrectly will cause Gitea
to not start.
- `RUN_MODE`: **prod**: Application run mode, affects performance and debugging. Either "dev", "prod" or "test".
- `RUN_MODE`: **prod**: Application run mode, affects performance and debugging: `dev` or `prod`, default is `prod`. Mode `dev` makes Gitea easier to develop and debug, values other than `dev` are treated as `prod` which is for production use.
## Repository (`repository`)
@ -144,6 +144,7 @@ limit defined in `REPO_SIZE_LIMIT` or at the repository itself.
### Repository - Issue (`repository.issue`)
- `LOCK_REASONS`: **Too heated,Off-topic,Resolved,Spam**: A list of reasons why a Pull Request or Issue can be locked
- `MAX_PINNED`: **3**: Maximum number of pinned Issues. Set to 0 to disable pinning Issues.
### Repository - Upload (`repository.upload`)
@ -468,6 +469,7 @@ relation to port exhaustion.
- `ISSUE_INDEXER_PATH`: **indexers/issues.bleve**: Index file used for issue search; available when ISSUE_INDEXER_TYPE is bleve and elasticsearch. Relative paths will be made absolute against _`AppWorkPath`_.
- `REPO_INDEXER_ENABLED`: **false**: Enables code search (uses a lot of disk space, about 6 times more than the repository size).
- `REPO_INDEXER_REPO_TYPES`: **sources,forks,mirrors,templates**: Repo indexer units. The items to index could be `sources`, `forks`, `mirrors`, `templates` or any combination of them separated by a comma. If empty then it defaults to `sources` only, as if you'd like to disable fully please see `REPO_INDEXER_ENABLED`.
- `REPO_INDEXER_TYPE`: **bleve**: Code search engine type, could be `bleve` or `elasticsearch`.
- `REPO_INDEXER_PATH`: **indexers/repos.bleve**: Index file used for code search.
- `REPO_INDEXER_CONN_STR`: ****: Code indexer connection string, available when `REPO_INDEXER_TYPE` is elasticsearch. i.e. http://elastic:changeme@localhost:9200
@ -517,7 +519,7 @@ And the following unique queues:
- `INSTALL_LOCK`: **false**: Controls access to the installation page. When set to "true", the installation page is not accessible.
- `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.
- `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`: **7**: Cookie lifetime, in days.
- `COOKIE_USERNAME`: **gitea\_awesome**: Name of the cookie used to store the current username.
- `COOKIE_REMEMBER_NAME`: **gitea\_incredible**: Name of cookie used to store authentication
@ -543,7 +545,7 @@ And the following unique queues:
- `ONLY_ALLOW_PUSH_IF_GITEA_ENVIRONMENT_SET`: **true**: Set to `false` to allow local users to push to gitea-repositories without setting up the Gitea environment. This is not recommended and if you want local users to push to Gitea repositories you should set the environment appropriately.
- `IMPORT_LOCAL_PATHS`: **false**: Set to `false` to prevent all users (including admin) from importing local path on server.
- `INTERNAL_TOKEN`: **\<random at every install if no uri set\>**: Secret used to validate communication within Gitea binary.
- `INTERNAL_TOKEN_URI`: **<empty>**: Instead of defining INTERNAL_TOKEN in the configuration, this configuration option can be used to give Gitea a path to a file that contains the internal token (example value: `file:/etc/gitea/internal_token`)
- `INTERNAL_TOKEN_URI`: **\<empty\>**: Instead of defining INTERNAL_TOKEN in the configuration, this configuration option can be used to give Gitea a path to a file that contains the internal token (example value: `file:/etc/gitea/internal_token`)
- `PASSWORD_HASH_ALGO`: **pbkdf2**: The hash algorithm to use \[argon2, pbkdf2, pbkdf2_v1, pbkdf2_hi, scrypt, bcrypt\], argon2 and scrypt will spend significant amounts of memory.
- Note: The default parameters for `pbkdf2` hashing have changed - the previous settings are available as `pbkdf2_v1` but are not recommended.
- The hash functions may be tuned by using `$` after the algorithm:
@ -574,8 +576,8 @@ And the following unique queues:
## Camo (`camo`)
- `ENABLED`: **false**: Enable media proxy, we support images only at the moment.
- `SERVER_URL`: **<empty>**: URL of camo server, it **is required** if camo is enabled.
- `HMAC_KEY`: **<empty>**: Provide the HMAC key for encoding URLs, it **is required** if camo is enabled.
- `SERVER_URL`: **\<empty\>**: URL of camo server, it **is required** if camo is enabled.
- `HMAC_KEY`: **\<empty\>**: Provide the HMAC key for encoding URLs, it **is required** if camo is enabled.
- `ALLWAYS`: **false**: Set to true to use camo for both HTTP and HTTPS content, otherwise only non-HTTPS URLs are proxied
## OpenID (`openid`)
@ -1121,7 +1123,7 @@ Gitea can support Markup using external tools. The example below will add a mark
ENABLED = true
NEED_POSTPROCESS = true
FILE_EXTENSIONS = .adoc,.asciidoc
RENDER_COMMAND = "asciidoc --out-file=- -"
RENDER_COMMAND = "asciidoctor --embedded --safe-mode=secure --out-file=- -"
IS_INPUT_FILE = false
```

2
docs/content/doc/administration/config-cheat-sheet.zh-cn.md
View File

@ -337,7 +337,7 @@ test01.xls: application/vnd.ms-excel; charset=binary
ENABLED = false
NEED_POSTPROCESS = true
FILE_EXTENSIONS = .adoc,.asciidoc
RENDER_COMMAND = "asciidoc --out-file=- -"
RENDER_COMMAND = "asciidoctor --embedded --safe-mode=secure --out-file=- -"
IS_INPUT_FILE = false
```

3
docs/content/doc/contributing/guidelines-backend.en-us.md
View File

@ -37,7 +37,7 @@ To maintain understandable code and avoid circular dependencies it is important
- `cmd`: All Gitea actual sub commands includes web, doctor, serv, hooks, admin and etc. `web` will start the web service. `serv` and `hooks` will be invoked by Git or OpenSSH. Other sub commands could help to maintain Gitea.
- `tests`: Common test utility functions
- `tests/integration`: Integration tests, to test back-end regressions
- `tests/e2e`: E2e tests, to test test front-end <> back-end compatibility and visual regressions.
- `tests/e2e`: E2e tests, to test front-end and back-end compatibility and visual regressions.
- `models`: Contains the data structures used by xorm to construct database tables. It also contains functions to query and update the database. Dependencies to other Gitea code should be avoided. You can make exceptions in cases such as logging.
- `models/db`: Basic database operations. All other `models/xxx` packages should depend on this package. The `GetEngine` function should only be invoked from `models/`.
- `models/fixtures`: Sample data used in unit tests and integration tests. One `yml` file means one table which will be loaded into database when beginning the tests.
@ -72,7 +72,6 @@ So services must be allowed to create a database transaction. Here is some examp
// services/repository/repository.go
func CreateXXXX() error {
return db.WithTx(func(ctx context.Context) error {
e := db.GetEngine(ctx)
// do something, if err is returned, it will rollback automatically
if err := issues.UpdateIssue(ctx, repoID); err != nil {
// ...

123
docs/content/doc/contributing/guidelines-backend.zh-cn.md Normal file
View File

@ -0,0 +1,123 @@
---
date: "2023-05-25T23:41:00+08:00"
title: "后端开发指南"
slug: "guidelines-backend"
weight: 20
toc: false
draft: false
aliases:
- /zh-cn/guidelines-backend
menu:
sidebar:
parent: "contributing"
name: "后端开发指南"
weight: 20
identifier: "guidelines-backend"
---
# 后端开发指南
**目录**
{{< toc >}}
## 背景
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`中。

4
docs/content/doc/contributing/guidelines-frontend.en-us.md
View File

@ -2,7 +2,7 @@
date: "2021-10-13T16:00:00+02:00"
title: "Guidelines for Frontend Development"
slug: "guidelines-frontend"
weight: 20
weight: 30
toc: false
draft: false
aliases:
@ -11,7 +11,7 @@ menu:
sidebar:
parent: "contributing"
name: "Guidelines for Frontend"
weight: 20
weight: 30
identifier: "guidelines-frontend"
---

138
docs/content/doc/contributing/guidelines-frontend.zh-cn.md Normal file
View File

@ -0,0 +1,138 @@
---
date: "2023-05-25T16:00:00+02:00"
title: "前端开发指南"
slug: "guidelines-frontend"
weight: 20
toc: false
draft: false
aliases:
- /zh-cn/guidelines-frontend
menu:
sidebar:
parent: "contributing"
name: "前端开发指南"
weight: 20
identifier: "guidelines-frontend"
---
# 前端开发指南
**目录**
{{< toc >}}
## 背景
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. Gitea 的 tailwind-style CSS 类使用`gt-`前缀（`gt-relative`），而 Gitea 自身的私有框架级 CSS 类使用`g-`前缀（`g-modal-confirm`）。
### 可访问性 / ARIA
在历史上，Gitea大量使用了可访问性不友好的框架 Fomantic UI。
Gitea使用一些补丁使Fomantic UI更具可访问性（参见`aria.js`和`aria.md`），
但仍然存在许多问题需要大量的工作和时间来修复。
### 框架使用
不建议混合使用不同的框架，这会使代码难以维护。
一个 JavaScript 模块应遵循一个主要框架，并遵循该框架的最佳实践。
推荐的实现方式：
* Vue + Vanilla JS
* Fomantic-UI（jQuery）
* Vanilla JS
不推荐的实现方式：
* Vue + Fomantic-UI（jQuery）
* jQuery + Vanilla JS
为了保持界面一致，Vue 组件可以使用 Fomantic-UI 的 CSS 类。
尽管不建议混合使用不同的框架，
但如果混合使用是必要的，并且代码设计良好且易于维护，也可以工作。
### 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 时发出警告。
### HTML 属性和 dataset
禁止使用`dataset`，它的驼峰命名行为使得搜索属性变得困难。
然而，仍然存在一些特殊情况，因此当前的准则是：
* 对于旧代码：
* 应将`$.data()`重构为`$.attr()`。
* 在极少数情况下，可以使用`$.data()`将一些非字符串数据绑定到元素上，但强烈不推荐使用。
* 对于新代码：
* 不应使用`node.dataset`，而应使用`node.getAttribute`。
* 不要将任何用户数据绑定到 DOM 节点上，使用合适的设计模式描述节点和数据之间的关系。
### 显示/隐藏元素
* 推荐在Vue组件中使用`v-if`和`v-show`来显示/隐藏元素。
* Go 模板代码应使用 Gitea 的 `.gt-hidden` 和 `showElem()/hideElem()/toggleElem()` 来显示/隐藏元素，请参阅`.gt-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 代码分离。

4
docs/content/doc/contributing/guidelines-refactoring.en-us.md
View File

@ -2,7 +2,7 @@
date: "2023-02-14T00:00:00+00:00"
title: "Guidelines for Refactoring"
slug: "guidelines-refactoring"
weight: 20
weight: 40
toc: false
draft: false
aliases:
@ -11,7 +11,7 @@ menu:
sidebar:
parent: "contributing"
name: "Guidelines for Refactoring"
weight: 20
weight: 40
identifier: "guidelines-refactoring"
---

53
docs/content/doc/contributing/guidelines-refactoring.zh-cn.md Normal file
View File

@ -0,0 +1,53 @@
---
date: "2023-05-25T00:00:00+00:00"
title: "重构指南"
slug: "guidelines-refactoring"
weight: 20
toc: false
draft: false
aliases:
- /zh-cn/guidelines-refactoring
menu:
sidebar:
parent: "contributing"
name: "重构指南"
weight: 20
identifier: "guidelines-refactoring"
---
# 重构指南
**目录**
{{< toc >}}
## 背景
自2014年2月12日编写了第一行代码以来，Gitea已经发展成为一个庞大的项目。
因此，代码库变得越来越大。代码库越大，维护就越困难。
存在许多过时的机制，许多框架混合在一起，一些遗留代码可能会导致错误并阻碍新功能的开发。
为了使代码库更易于维护，使Gitea变得更好，开发人员应牢记使用现代机制来重构旧代码。
本文档是关于重构代码库的指南集合。
## 重构建议
* 设计更多关于未来的内容，而不仅仅解决当前问题。
* 减少模糊性，减少冲突，提高可维护性。
* 描述重构，例如：
* 为什么需要重构。
* 如何解决旧问题。
* 重构的优点/缺点是什么。
* 只做必要的更改，尽量保留旧逻辑。
* 引入一些中间步骤，使重构更容易审查，完整的重构计划可以在几个PR中完成。
* 如果存在分歧，应该请TOC（技术监督委员会）参与决策。
* 添加必要的测试以确保重构的正确性。
* 非错误重构优先在里程碑的开始时进行，这样可以更容易地在发布之前发现问题。
## 审查和合并建议
* 重构的PR不应该长时间保持打开状态（通常为7天），应尽快进行审查。
* 重构的PR应尽快合并，不应被其他PR阻塞。
* 如果TOC没有异议，重构的PR可以在7天后由一名核心成员（非作者）批准后合并。
* 如果最终结果良好，容忍一些不完美/临时的步骤。
* 如果重构是必要的，容忍一些回归错误，并尽快修复错误。

5
docs/content/doc/contributing/translation.de-de.md → docs/content/doc/contributing/localization.de-de.md
View File

@ -1,15 +1,16 @@
---
date: "2021-01-22T00:00:00+02:00"
title: "Übersetzungs Richtlinien"
slug: "localization"
weight: 70
toc: true
toc: false
draft: false
menu:
sidebar:
parent: "contributing"
name: "Übersetzungsrichtlinien"
weight: 70
identifier: "translation-guidelines"
identifier: "localization"
---
## Allgemeines

8
docs/content/doc/contributing/localization.en-us.md
View File

@ -2,7 +2,7 @@
date: "2016-12-01T16:00:00+02:00"
title: "Localization"
slug: "localization"
weight: 10
weight: 70
toc: false
draft: false
aliases:
@ -11,7 +11,7 @@ menu:
sidebar:
parent: "contributing"
name: "Localization"
weight: 20
weight: 70
identifier: "localization"
---
@ -33,3 +33,7 @@ After a translation has been accepted, it will be reflected in the main reposito
At the time of writing, this means that a changed translation may not appear until the following Gitea release.
If you use a bleeding edge build, it should appear as soon as you update after the change is synced.
# How to Contribute
Different Languages have different translation guidelines. Please visit the respective page for more information.

4
docs/content/doc/contributing/localization.zh-cn.md
View File

@ -2,7 +2,7 @@
date: "2016-12-01T16:00:00+02:00"
title: "本地化"
slug: "localization"
weight: 20
weight: 70
toc: false
draft: false
aliases:
@ -11,7 +11,7 @@ menu:
sidebar:
parent: "contributing"
name: "本地化"
weight: 20
weight: 70
identifier: "localization"
---

4
docs/content/doc/contributing/localization.zh-tw.md
View File

@ -2,7 +2,7 @@
date: "2016-12-01T16:00:00+02:00"
title: "在地化"
slug: "localization"
weight: 20
weight: 70
toc: false
draft: false
aliases:
@ -11,7 +11,7 @@ menu:
sidebar:
parent: "contributing"
name: "在地化"
weight: 20
weight: 70
identifier: "localization"
---

17
docs/content/doc/contributing/translation.en-us.md
View File

@ -1,17 +0,0 @@
---
date: "2021-01-22T00:00:00+02:00"
title: "Translation Guidelines"
weight: 70
toc: true
draft: false
menu:
sidebar:
parent: "contributing"
name: "Translation Guidelines"
weight: 70
identifier: "translation-guidelines"
---
This place is used to provide a common set of rules to make sure the translation is consistent.
* [German](/de-de/übersetzungs-richtlinien/)

17
docs/content/doc/contributing/translation.zh-cn.md Normal file
View File

@ -0,0 +1,17 @@
---
date: "2023-05-25T00:00:00+02:00"
title: "翻译指南"
weight: 70
toc: true
draft: false
menu:
sidebar:
parent: "contributing"
name: "翻译指南"
weight: 70
identifier: "translation-guidelines"
---
本页面用于提供一套通用规则，以确保翻译的一致性。
* [German](/de-de/übersetzungs-richtlinien/)

4
docs/content/doc/development/hacking-on-gitea.zh-cn.md
View File

@ -249,8 +249,8 @@ make swagger-check
### 创建新的配置选项
创建新的配置选项时，将它们添加到 `modules/setting` 的对应文件。您应该将信息添加到 `custom/conf/app.ini`
并到 <a href = '{{ < relref "doc/administration/config-cheat-sheet.en-us.md" > }}'>配置备忘单</a>
在 `docs/content/doc/advanced/config-cheat-sheet.en-us.md` 中找到
并到 <a href = '{{ < relref "doc/administration/config-cheat-sheet.zh-cn.md" > }}'>配置备忘单</a>
在 `docs/content/doc/advanced/config-cheat-sheet.zh-cn.md` 中找到
### 更改Logo

46
docs/content/doc/development/integrations.zh-cn.md Normal file
View File

@ -0,0 +1,46 @@
---
date: "2023-05-25T17:29:00+08:00"
title: "集成"
slug: "integrations"
weight: 65
toc: false
draft: false
aliases:
- /zh-cn/integrations
menu:
sidebar:
parent: "development"
name: "集成"
weight: 65
identifier: "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!
```

40
docs/content/doc/development/migrations.zh-cn.md Normal file
View File

@ -0,0 +1,40 @@
---
date: "2023-05-25T17:29:00+08:00"
title: "迁移界面"
slug: "migrations-interfaces"
weight: 55
toc: false
draft: false
aliases:
- /zh-cn/migrations-interfaces
menu:
sidebar:
parent: "development"
name: "迁移界面"
weight: 55
identifier: "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)中找到这些接口。

472
docs/content/doc/help/faq.zh-cn.md Normal file
View File

@ -0,0 +1,472 @@
---
date: "2023-05-25T16:00:00+02:00"
title: "常见问题"
slug: "faq"
weight: 5
toc: false
draft: false
aliases:
- /zh-cn/faq
menu:
sidebar:
parent: "help"
name: "常见问题"
weight: 5
identifier: "faq"
---
# 常见问题 <!-- omit in toc -->
本页面包含一些常见问题和答案。
有关更多帮助资源，请查看所有[支持选项]({{< relref "doc/help/support.zh-cn.md" >}})。
**目录**
{{< toc >}}
## 1.x和1.x.x下载之间的区别
以1.7.x版本为例。
**注意：**此示例也适用于Docker镜像！
在我们的[下载页面](https://dl.gitea.io/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.9.146或更低]({{< relref "doc/installation/upgrade-from-gogs.zh-cn.md" >}})
- [Gogs版本0.11.46.0418](https://github.com/go-gitea/gitea/issues/4286)
要从GitHub迁移到Gitea，您可以使用Gitea内置的迁移表单。
为了迁移诸如问题、拉取请求等项目，您需要至少输入您的用户名。
[Example (requires login)](https://try.gitea.io/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. 如果使用反向代理，请确保按照[反向代理指南]({{< relref "doc/administration/reverse-proxies.zh-cn.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解决此问题，请参阅[反向代理指南]({{< relref "doc/administration/reverse-proxies.zh-cn.md" >}})。
## 自定义模板无法加载或运行错误
Gitea的自定义模板必须将其添加到正确的位置，否则Gitea将无法找到并使用自定义模板。
模板的正确路径应该相对于`CustomPath`。
1. 要找到`CustomPath`，请在站点管理 -> 配置 中查找自定义文件根路径。
如果找不到，请尝试`echo $GITEA_CUSTOM`。
2. 如果仍然找不到，默认值可以被[计算]({{< relref "doc/help/faq.zh-cn.md#where-does-gitea-store-what-file" >}})
3. 如果仍然找不到路径，则可以参考[自定义Gitea]({{< relref "doc/administration/customizing-gitea.zh-cn.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的用户。
## 设置日志记录
- [官方文档]({{< relref "doc/administration/logging-config.zh-cn.md" >}})
## 什么是Swagger？
[Swagger](https://swagger.io/) 是Gitea用于其API文档的工具。
所有Gitea实例都有内置的API，无法完全禁用它。
但是，您可以在app.ini的api部分将ENABLE_SWAGGER设置为false，以禁用其文档显示。
有关更多信息，请参阅Gitea的[API文档]({{< relref "doc/development/api-usage.zh-cn.md" >}})。
您可以在上查看最新的API（例如）<https://try.gitea.io/api/swagger>。
您还可以在上查看`swagger.json`文件的示例 <https://try.gitea.io/swagger.v1.json>。
## 调整服务器用于公共/私有使用
### 防止垃圾邮件发送者
有多种方法可以组合使用来防止垃圾邮件发送者：
1. 通过设置电子邮件域名的白名单或黑名单。
2. 通过设置一些域名或者OpenID白名单（见下文）。
3. 在您的`app.ini`中将`ENABLE_CAPTCHA`设置为`true`，并正确配置`RECAPTCHA_SECRET`和 `RECAPTCHA_SITEKEY`。
4. 将`DISABLE_REGISTRATION`设置为`true`，并通过 [CLI]({{< relref "doc/administration/command-line.zh-cn.md" >}})、[API]({{< relref "doc/development/api-usage.zh-cn.md" >}}) 或 Gitea 的管理界面创建新用户。
### 仅允许/阻止特定的电子邮件域名
您可以在`app.ini`中的`[service]`下的配置`EMAIL_DOMAIN_WHITELIST` 或 `EMAIL_DOMAIN_BLOCKLIST`。
### 仅允许/阻止特定的 OpenID 提供商
您可以在`app.ini`的`[openid]`下配置`WHITELISTED_URI`或`BLACKLISTED_URIS`。
**注意**： 白名单优先，如果白名单非空，则忽略黑名单。
### 仅允许发布问题的用户
目前实现这一点的方法是创建/修改一个具有最大仓库创建限制为 0 的用户。
### 受限制的用户
受限制的用户仅能访问其组织/团队成员和协作所在的内容的子集，而忽略组织/仓库等的公共标志。
示例用例：一个公司运行一个需要登录的 Gitea 实例。大多数仓库是公开的（所有同事都可以访问/浏览）。
在某些情况下，某个客户或第三方需要访问特定的仓库，并且只能访问该仓库。通过将此类客户帐户设置为受限制帐户，并使用团队成员身份和/或协作来授予所需的任何访问权限，可以简单地实现这一点，而无需使所有内容都变为私有。
### 启用 Fail2ban
使用 [Fail2Ban]({{< relref "doc/administration/fail2ban-setup.zh-cn.md" >}}) 监视并阻止基于日志模式的自动登录尝试或其他恶意行为。
## 如何添加/使用自定义主题
Gitea 目前支持三个官方主题，分别是 `gitea`（亮色）、`arc-green`（暗色）和 `auto`（根据操作系统设置自动切换前两个主题）。
要添加自己的主题，目前唯一的方法是提供一个完整的主题（不仅仅是颜色覆盖）。
假设我们的主题是 `arc-blue`（这是一个真实的主题，可以在[此问题](https://github.com/go-gitea/gitea/issues/6011)中找到）
将`.css`文件命名为`theme-arc-blue.css`并将其添加到`custom/public/css`文件夹中
通过将`arc-blue`添加到`app.ini`中的`THEMES`列表中，允许用户使用该主题
## SSHD vs 内建SSH
SSHD是大多数Unix系统上内建的SSH服务器。
Gitea还提供了自己的SSH服务器，用于在SSHD不可用时使用。
## Gitea运行缓慢
导致此问题的最常见原因是加载联合头像。
您可以通过在`app.ini`中将`ENABLE_FEDERATED_AVATAR`设置为`false`来关闭此功能。
还有一个可能需要更改的选项是在`app.ini`中将`DISABLE_GRAVATAR`设置为`true`。
## 无法创建仓库/文件
请确保Gitea具有足够的权限来写入其主目录和数据目录。
参见[AppDataPath 和 RepoRootPath]({{< relref "doc/help/faq.zh-cn.md#where-does-gitea-store-what-file" >}})
**适用于Arch用户的注意事项：**在撰写本文时，Arch软件包的systemd文件包含了以下行：
`ReadWritePaths=/etc/gitea/app.ini`
这将使得Gitea无法写入其他路径。
## 翻译不正确/如何添加更多翻译
我们当前的翻译是在我们的[Crowdin项目](https://crowdin.com/project/gitea)上众包进行的
无论您想要更改翻译还是添加新的翻译，都需要在Crowdin集成中进行，因为所有翻译都会被CI覆盖。
## 推送钩子/ Webhook未运行
如果您可以推送但无法在主页仪表板上看到推送活动，或者推送不触发Webhook，有几种可能性：
1. Git钩子不同步：在站点管理面板上运行“重新同步所有仓库的pre-receive、update和post-receive钩子”
2. Git仓库（和钩子）存储在一些不支持脚本执行的文件系统上（例如由NAS挂载），请确保文件系统支持`chmod a+x any-script`
3. 如果您使用的是Docker，请确保Docker Server（而不是客户端）的版本 >= 20.10.6
## SSH问题
如果无法通过`ssh`访问仓库，但`https`正常工作，请考虑以下情况。
首先，请确保您可以通过SSH访问Gitea。
`ssh git@myremote.example`
如果连接成功，您应该会收到以下错误消息：
```
Hi there, You've successfully authenticated, but Gitea does not provide shell access.
If this is unexpected, please log in with password and setup Gitea under another user.
```
如果您收到以上消息但仍然连接成功，这意味着您的 SSH 密钥**没有**由 Gitea 管理。这意味着钩子不会运行，在其他一些潜在问题中也包括在内。
如果您无法连接，可能是因为您的 SSH 密钥在本地配置不正确。
这是针对 SSH 而不是 Gitea 的问题，因此在此不涉及。
### SSH 常见错误
```
Permission denied (publickey).
fatal: Could not read from remote repository.
```
此错误表示服务器拒绝登录尝试，
请检查以下事项：
- 在客户端：
- 确保公钥和私钥已添加到正确的 Gitea 用户。
- 确保远程 URL 中没有任何问题。特别是，请确保∂
Git 用户（@ 之前的部分）的名称拼写正确。
- 确保客户端机器上的公钥和私钥正确无误。
- 在服务器上：
- 确保存储库存在并且命名正确。
- 检查系统用户主目录中的 `.ssh` 目录的权限。
- 验证正确的公钥是否已添加到 `.ssh/authorized_keys` 中。
尝试在 Gitea 管理面板上运行
`Rewrite '.ssh/authorized_keys' file (for Gitea SSH keys)`。
- 查看 Gitea 日志。
- 查看 /var/log/auth（或类似的文件）。
- 检查存储库的权限。
以下是一个示例，其中缺少公共 SSH 密钥，
认证成功，但是其他设置导致 SSH 无法访问正确的
存储库。
```
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.
```
在这种情况下，请检查以下设置：
- 在服务器上：
- 确保`git`系统用户设置了可用的 shell
- 使用`getent passwd git | cut -d: -f7`进行验证
- 可以使用`usermod`或`chsh`进行修改。
- 确保`.ssh/authorized_keys`中的`gitea serv`命令使用
正确的配置文件。
## 迁移带有标签的存储库后缺失发布版本
要迁移带有所有标签的存储库，您需要执行两个操作：
- 推送标签到存储库：
```
git push --tags
```
- 在 Gitea 中重新同步所有存储库的标签：
```
gitea admin repo-sync-releases
```
## LFS 问题
针对涉及 LFS 数据上传的问题
```
batch response: Authentication required: Authorization error: <GITEA_LFS_URL>/info/lfs/objects/batch
Check that you have proper access to the repository
error: failed to push some refs to '<GIT_REPO_URL>'
```
检查`app.ini`文件中的`LFS_HTTP_AUTH_EXPIRY`值。
默认情况下，LFS 令牌在 20 分钟后过期。如果您的连接速度较慢或文件较大（或两者都是），可能无法在时间限制内完成上传。
您可以将此值设置为`60m`或`120m`。
## 如何在启动 Gitea 之前创建用户
Gitea 提供了一个子命令`gitea migrate`来初始化数据库，然后您可以使用[管理 CLI 命令]({{< relref "doc/administration/command-line.zh-cn.md#admin" >}})像正常情况下添加用户。
## 如何启用密码重置
没有密码重置的设置。当配置了[邮件服务]({{< relref "doc/administration/email-setup.zh-cn.md" >}})时，密码重置将自动启用；否则将被禁用。
## 如何更改用户的密码
- 作为管理员，您可以更改任何用户的密码（并可选择强制其在下次登录时更改密码）...
- 转到您的`站点管理 -> 用户账户`页面并编辑用户。
- 使用[管理 CLI 命令]({{< relref "doc/administration/command-line.zh-cn.md#admin" >}})。
请注意，大多数命令还需要一个[全局标志]({{< relref "doc/administration/command-line.zh-cn.- md#global-options" >}})来指向正确的配置。
- 作为**用户**，您可以更改密码...
- 在您的账户的`设置 -> 账户`页面（此方法**需要**您知道当前密码）。
- 使用`忘记密码`链接。
如果`忘记密码/账户恢复`页面被禁用，请联系管理员配置[邮件服务]({{< relref "doc/administration/email-setup.zh-cn.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 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;`。
如果您使用的是 MySQL 5，另一个可能的修复方法是：
```mysql
SET GLOBAL innodb_file_format=Barracuda;
SET GLOBAL innodb_file_per_table=1;
SET GLOBAL innodb_large_prefix=1;
```
## 为什么 MySQL 上的 Emoji 显示错误
不幸的是，MySQL 的`utf8`字符集不完全允许所有可能的 UTF-8 字符，特别是 Emoji。
他们创建了一个名为 `utf8mb4`的字符集和校对规则，允许存储 Emoji，但使用
utf8 字符集的表和连接将不会使用它。
请运行 `gitea convert` 或对数据库运行`ALTER DATABASE database_name CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;`
并对每个表运行
`ALTER TABLE table_name CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;`。
您还需要将`app.ini`文件中的数据库字符集设置为`CHARSET=utf8mb4`。
## 为什么 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>`来查看。
要收集日志以进行帮助和问题报告，请参阅[支持选项]({{< relref "doc/help/support.zh-cn.md" >}})。
## 初始日志记录
在 Gitea 读取配置文件并设置其日志记录之前，它会将一些内容记录到标准输出，以帮助调试日志记录无法工作的情况。
您可以通过设置`--quiet`或`-q`选项来停止此日志记录。请注意，这只会在 Gitea 设置自己的日志记录之前停止日志记录。
如果您报告了错误或问题，必须提供这些信息以恢复初始日志记录。
只有在完全配置了所有内容之后，您才应该设置此选项。
## 在数据库启动期间出现有关结构默认值的警告
有时，在迁移过程中，旧列和默认值可能在数据库架构中保持不变。
这可能会导致警告，例如：
```
2020/08/02 11:32:29 ...rm/session_schema.go:360:Sync2() [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`]({{< relref "doc/administration/config-cheat-sheet.zh-cn.md#repository" >}}) 获得类似的权限。
- 如果上述步骤都正确执行，您应该能够选择要采用的存储库。
- 如果没有找到存储库，请启用[调试日志记录]({{< relref "doc/administration/config-cheat-sheet.zh-cn.md#repository" >}})以检查是否有特定错误。

307
docs/content/doc/installation/database-preparation.zh-cn.md Normal file
View File

@ -0,0 +1,307 @@
---
date: "2020-01-16"
title: "数据库准备"
slug: "database-prep"
weight: 10
toc: false
draft: false
aliases:
- /zh-cn/database-prep
menu:
sidebar:
parent: "installation"
name: "数据库准备"
weight: 10
identifier: "database-prep"
---
# 数据库准备
在使用 Gitea 前，您需要准备一个数据库。Gitea 支持 PostgreSQL（>=10）、MySQL（>=5.7）、SQLite 和 MSSQL（>=2008R2 SP3）这几种数据库。本页将指导您准备数据库。由于 PostgreSQL 和 MySQL 在生产环境中被广泛使用，因此本文档将仅涵盖这两种数据库。如果您计划使用 SQLite，则可以忽略本章内容。
数据库实例可以与 Gitea 实例在相同机器上（本地数据库），也可以与 Gitea 实例在不同机器上（远程数据库）。
注意：以下所有步骤要求您的选择的数据库引擎已安装在您的系统上。对于远程数据库设置，请在数据库实例上安装服务器应用程序，在 Gitea 服务器上安装客户端程序。客户端程序用于测试 Gitea 服务器与数据库之间的连接，而 Gitea 本身使用 Go 提供的数据库驱动程序完成相同的任务。此外，请确保服务器和客户端使用相同的引擎版本，以使某些引擎功能正常工作。出于安全原因，请使用安全密码保护 `root`（MySQL）或 `postgres`（PostgreSQL）数据库超级用户。以下步骤假设您在数据库和 Gitea 服务器上都使用 Linux。
**目录**
{{< toc >}}
## MySQL
1. 对于远程数据库设置，您需要让 MySQL 监听您的 IP 地址。编辑数据库实例上的 `/etc/mysql/my.cnf` 文件中的 `bind-address` 选项为：
```ini
bind-address = 203.0.113.3
```
2. 在数据库实例上，使用 `root` 用户登录到数据库控制台：
```
mysql -u root -p
```
按提示输入密码。
3. 创建一个将被 Gitea 使用的数据库用户，并使用密码进行身份验证。以下示例中使用了 `'gitea'` 作为密码。请为您的实例使用一个安全密码。
对于本地数据库：
```sql
SET old_passwords=0;
CREATE USER 'gitea' IDENTIFIED BY 'gitea';
```
对于远程数据库：
```sql
SET old_passwords=0;
CREATE USER 'gitea'@'192.0.2.10' IDENTIFIED BY 'gitea';
```
其中 `192.0.2.10` 是您的 Gitea 实例的 IP 地址。
根据需要替换上述用户名和密码。
4. 使用 UTF-8 字符集和排序规则创建数据库。确保使用 `**utf8mb4**` 字符集，而不是 `utf8`，因为前者支持 _Basic Multilingual Plane_ 之外的所有 Unicode 字符（包括表情符号）。排序规则根据您预期的内容选择。如果不确定，可以使用 `unicode_ci` 或 `general_ci`。
```sql
CREATE DATABASE giteadb CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_unicode_ci';
```
根据需要替换数据库名称。
5. 将数据库上的所有权限授予上述创建的数据库用户。
对于本地数据库：
```sql
GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea';
FLUSH PRIVILEGES;
```
对于远程数据库：
```sql
GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea'@'192.0.2.10';
FLUSH PRIVILEGES;
```
6. 通过 exit 退出数据库控制台。
7. 在您的 Gitea 服务器上，测试与数据库的连接：
```
mysql -u gitea -h 203.0.113.3 -p giteadb
```
其中 `gitea` 是数据库用户名，`giteadb` 是数据库名称，`203.0.113.3` 是数据库实例的 IP 地址。对于本地数据库，省略 -h 选项。
到此您应该能够连接到数据库了。
## PostgreSQL
1. 对于远程数据库设置，通过编辑数据库实例上的 postgresql.conf 文件中的 listen_addresses 将 PostgreSQL 配置为监听您的 IP 地址：
```ini
listen_addresses = 'localhost, 203.0.113.3'
```
2. PostgreSQL 默认使用 `md5` 质询-响应加密方案进行密码身份验证。现在这个方案不再被认为是安全的。改用 SCRAM-SHA-256 方案，通过编辑数据库服务器上的` postgresql.conf` 配置文件：
```ini
password_encryption = scram-sha-256
```
重启 PostgreSQL 以应用该设置。
3. 在数据库服务器上，以超级用户身份登录到数据库控制台：
```
su -c "psql" - postgres
```
4. 创建具有登录权限和密码的数据库用户（在 PostgreSQL 术语中称为角色）。请使用安全的、强密码，而不是下面的 `'gitea'`：
```sql
CREATE ROLE gitea WITH LOGIN PASSWORD 'gitea';
```
根据需要替换用户名和密码。
5. 使用 UTF-8 字符集创建数据库，并由之前创建的数据库用户拥有。可以根据预期内容使用任何 `libc` 排序规则，使用 `LC_COLLATE` 和 `LC_CTYPE` 参数指定：
```sql
CREATE DATABASE giteadb WITH OWNER gitea TEMPLATE template0 ENCODING UTF8 LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8';
```
根据需要替换数据库名称。
6. 通过将以下身份验证规则添加到 `pg_hba.conf`，允许数据库用户访问上面创建的数据库。
对于本地数据库：
```ini
local giteadb gitea scram-sha-256
```
对于远程数据库：
```ini
host giteadb gitea 192.0.2.10/32 scram-sha-256
```
根据您自己的数据库名称、用户和 Gitea 实例的 IP 地址进行替换。
注意：`pg_hba.conf` 上的规则按顺序评估，也就是第一个匹配的规则将用于身份验证。您的 PostgreSQL 安装可能附带了适用于所有用户和数据库的通用身份验证规则。如果是这种情况，您可能需要将此处提供的规则放置在此类通用规则之上。
重启 PostgreSQL 以应用新的身份验证规则。
7. 在您的 Gitea 服务器上，测试与数据库的连接。
对于本地数据库：
```
psql -U gitea -d giteadb
```
对于远程数据库：
```
psql "postgres://gitea@203.0.113.3/giteadb"
```
其中 `gitea` 是数据库用户，`giteadb` 是数据库名称，`203.0.113.3` 是您的数据库实例的 IP 地址。
您应该会被提示输入数据库用户的密码，并连接到数据库。
## 使用 TLS 进行数据库连接
如果 Gitea 和您的数据库实例之间的通信是通过私有网络进行的，或者如果 Gitea 和数据库运行在同一台服务器上，那么可以省略本节，因为 Gitea 和数据库实例之间的安全性不会受到严重威胁。但是，如果数据库实例位于公共网络上，请使用 TLS 对数据库连接进行加密，以防止第三方拦截流量数据。
### 先决条件
- 您需要两个有效的 TLS 证书，一个用于数据库实例（数据库服务器），一个用于 Gitea 实例（数据库客户端）。两个证书都必须由受信任的 CA 签名。
- 数据库证书必须在 `X509v3 Extended Key Usage` 扩展属性中包含 `TLS Web Server Authentication`，而客户端证书则需要在相应的属性中包含 `TLS Web Client Authentication`。
- 在数据库服务器证书中，`Subject Alternative Name` 或 `Common Name` 条目之一必须是数据库实例的完全限定域名（FQDN）（例如 `db.example.com`）。在数据库客户端证书中，上述提到的条目之一必须包含 Gitea 将用于连接的数据库用户名。
- 您需要将 Gitea 和数据库服务器的域名映射到它们各自的 IP 地址。可以为它们设置 DNS 记录，也可以在每个系统上的 `/etc/hosts`（Windows 中的 `%WINDIR%\System32\drivers\etc\hosts`）中添加本地映射。这样可以通过域名而不是 IP 地址进行数据库连接。有关详细信息，请参阅您系统的文档。
### PostgreSQL
Gitea 使用的 PostgreSQL 驱动程序支持双向 TLS。在双向 TLS 中，数据库客户端和服务器通过将各自的证书发送给对方进行验证来相互认证。换句话说，服务器验证客户端证书，客户端验证服务器证书。
1. 在数据库实例所在的服务器上，放置以下凭据：
- `/path/to/postgresql.crt`: 数据库实例证书
- `/path/to/postgresql.key`: 数据库实例私钥
- `/path/to/root.crt`: 用于验证客户端证书的CA证书链
2. 在 `postgresql.conf` 中添加以下选项：
```ini
ssl = on
ssl_ca_file = '/path/to/root.crt'
ssl_cert_file = '/path/to/postgresql.crt'
ssl_key_file = '/path/to/postgresql.key'
ssl_min_protocol_version = 'TLSv1.2'
```
3. 根据 PostgreSQL 的要求，调整凭据的所有权和权限：
```
chown postgres:postgres /path/to/root.crt /path/to/postgresql.crt /path/to/postgresql.key
chmod 0600 /path/to/root.crt /path/to/postgresql.crt /path/to/postgresql.key
```
4. 编辑 `pg_hba.conf` 规则，仅允许 Gitea 数据库用户通过SSL连接，并要求客户端证书验证。
对于PostgreSQL 12：
```ini
hostssl giteadb gitea 192.0.2.10/32 scram-sha-256 clientcert=verify-full
```
对于PostgreSQL 11及更早版本：
```ini
hostssl giteadb gitea 192.0.2.10/32 scram-sha-256 clientcert=1
```
根据需要替换数据库名称、用户和 Gitea 实例的 IP 地址。
5. 重新启动 PostgreSQL 以应用上述配置。
6. 在运行 Gitea 实例的服务器上，将以下凭据放置在运行 Gitea 的用户的主目录下（例如 `git`）：
- `~/.postgresql/postgresql.crt`: 数据库客户端证书
- `~/.postgresql/postgresql.key`: 数据库客户端私钥
- `~/.postgresql/root.crt`: 用于验证服务器证书的CA证书链
注意：上述文件名在 PostgreSQL 中是硬编码的，无法更改。
7. 根据需要调整凭据、所有权和权限：
```
chown git:git ~/.postgresql/postgresql.crt ~/.postgresql/postgresql.key ~/.postgresql/root.crt
chown 0600 ~/.postgresql/postgresql.crt ~/.postgresql/postgresql.key ~/.postgresql/root.crt
```
8. 测试与数据库的连接：
```
psql "postgres://gitea@example.db/giteadb?sslmode=verify-full"
```
您将被提示输入数据库用户的密码，然后连接到数据库。
### MySQL
虽然 Gitea 使用的MySQL驱动程序也支持双向 TLS，但目前 Gitea 仅支持单向 TLS。有关详细信息，请参见工单＃10828。
在单向TLS中，数据库客户端在连接握手期间验证服务器发送的证书，而服务器则假定连接的客户端是合法的，因为不进行客户端证书验证。
1. 在数据库实例上放置以下凭据：
- `/path/to/mysql.crt`: 数据库实例证书
- `/path/to/mysql.key`: 数据库实例密钥
- `/path/to/ca.crt`: CA证书链。在单向TLS中不使用此文件，但用于验证双向TLS中的客户端证书。
2. 将以下选项添加到 `my.cnf`：
```ini
[mysqld]
ssl-ca = /path/to/ca.crt
ssl-cert = /path/to/mysql.crt
ssl-key = /path/to/mysql.key
tls-version = TLSv1.2,TLSv1.3
```
3. 调整凭据的所有权和权限：
```
chown mysql:mysql /path/to/ca.crt /path/to/mysql.crt /path/to/mysql.key
chmod 0600 /path/to/ca.crt /path/to/mysql.crt /path/to/mysql.key
```
4. 重新启动MySQL以应用设置。
5. Gitea 的数据库用户可能已经创建过，但只会对运行 Gitea 的服务器的 IP 地址进行身份验证。要对其域名进行身份验证，请重新创建用户，并设置其需要通过 TLS 连接到数据库：
```sql
DROP USER 'gitea'@'192.0.2.10';
CREATE USER 'gitea'@'example.gitea' IDENTIFIED BY 'gitea' REQUIRE SSL;
GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea'@'example.gitea';
FLUSH PRIVILEGES;
```
根据需要替换数据库用户名、密码和 Gitea 实例域名。
6. 确保用于验证数据库服务器证书的CA证书链位于数据库和 Gitea 服务器的系统证书存储中。请参考系统文档中有关将 CA 证书添加到证书存储的说明。
7. 在运行Gitea的服务器上，测试与数据库的连接：
```
mysql -u gitea -h example.db -p --ssl
```
至此应该成功连接到数据库了。

6
docs/content/doc/installation/from-binary.zh-cn.md
View File

@ -1,6 +1,6 @@
---
date: "2016-12-01T16:00:00+02:00"
title: "从二进制安装"
title: "使用二进制文件安装"
slug: "install-from-binary"
weight: 15
toc: false
@ -10,12 +10,12 @@ aliases:
menu:
sidebar:
parent: "installation"
name: "从二进制安装"
name: "使用二进制文件安装"
weight: 15
identifier: "install-from-binary"
---
# 从二进制安装
# 使用二进制文件安装
所有打包的二进制程序均包含 SQLite，MySQL 和 PostgreSQL 的数据库连接支持，同时网站的静态资源均已嵌入到可执行程序中，这一点和曾经的 Gogs 有所不同。

6
docs/content/doc/installation/from-source.zh-cn.md
View File

@ -1,6 +1,6 @@
---
date: "2016-12-01T16:00:00+02:00"
title: "从源代码安装"
title: "使用源代码安装"
slug: "install-from-source"
weight: 30
toc: false
@ -10,12 +10,12 @@ aliases:
menu:
sidebar:
parent: "installation"
name: "从源代码安装"
name: "使用源代码安装"
weight: 30
identifier: "install-from-source"
---
# 从源代码安装
# 使用源代码安装
首先你需要安装Golang，关于Golang的安装，参见[官方文档](https://golang.google.cn/doc/install)。

57
docs/content/doc/installation/on-cloud-provider.zh-cn.md Normal file
View File

@ -0,0 +1,57 @@
---
date: "2016-12-01T16:00:00+02:00"
title: "在云服务器中安装 Gitea"
slug: "install-on-cloud-provider"
weight: 90
toc: false
draft: false
aliases:
- /zh-cn/install-on-cloud-provider
menu:
sidebar:
parent: "installation"
name: "在云服务器中安装 Gitea"
weight: 90
identifier: "install-on-cloud-provider"
---
# 在云服务器上安装 Gitea
**Table of Contents**
{{< toc >}}
## Cloudron
Gitea 可以在 [Cloudron](https://cloudron.io) 上进行一键安装。
Cloudron 使得在您的服务器上运行 Gitea，并保持其更新和安全变得简单。
[![Install](/cloudron.svg)](https://cloudron.io/button.html?app=io.gitea.cloudronapp)
Gitea软件包的维护地址在[这里](https://git.cloudron.io/cloudron/gitea-app).
这里有一个[demo 实例](https://my.demo.cloudron.io) (用户名: cloudron 密码: cloudron) 您可以在其中尝试运行Gitea。
## Vultr
Gitea 可以在 [Vultr](https://www.vultr.com) 的市场中被找到。
要将 Gitea 部署到 Vultr，请参考 [Vultr Marketplace](https://www.vultr.com/marketplace/apps/gitea).
## DigitalOcean
[DigitalOcean](https://www.digitalocean.com) 将 Gitea 作为其市场中的一个 droplet。
要将 Gitea 部署到 DigitalOcean, 请参考 [DigitalOcean Marketplace](https://marketplace.digitalocean.com/apps/gitea).
## Linode
[Linode](https://www.linode.com/) 将 Gitea 作为其市场中的一个应用程序.
要将 Gitea 部署到 Linode, 请参考 [Linode Marketplace](https://www.linode.com/marketplace/apps/linode/gitea/).
## alwaysdata
[alwaysdata](https://www.alwaysdata.com/) 将 Gitea 作为其市场中的一个 droplet.
要将 Gitea 部署到 alwaysdata, 请参考 [alwaysdata Marketplace](https://www.alwaysdata.com/en/marketplace/gitea/).

4
docs/content/doc/installation/on-kubernetes.zh-cn.md
View File

@ -1,6 +1,6 @@
---
date: "2020-03-19T19:27:00+02:00"
title: "在 Kubernetes 安装 Gitea"
title: "在 Kubernetes 中安装 Gitea"
slug: "install-on-kubernetes"
weight: 80
toc: false
@ -10,7 +10,7 @@ aliases:
menu:
sidebar:
parent: "installation"
name: "Kubernetes"
name: "在 Kubernetes 中安装 Gitea"
weight: 80
identifier: "install-on-kubernetes"
---

332
docs/content/doc/installation/with-docker-rootless.zh-cn.md Normal file
View File

@ -0,0 +1,332 @@
---
date: "2020-02-09T20:00:00+02:00"
title: "使用 Docker 安装 (rootless)"
slug: "install-with-docker-rootless"
weight: 60
toc: false
draft: false
aliases:
- /zh-cn/install-with-docker-rootless
menu:
sidebar:
parent: "installation"
name: "使用 Docker 安装 (rootless)"
weight: 60
identifier: "install-with-docker-rootless"
---
# 使用 Docker 安装
Gitea 在其 Docker Hub 组织中提供自动更新的 Docker 镜像。您可以始终使用最新的稳定标签，或使用其他处理 Docker 镜像更新的服务。
rootless 镜像使用 Gitea 内部 SSH 功能来提供 Git 协议，但不支持 OpenSSH。
本参考设置指南将用户引导通过基于 `docker-compose` 的设置。但是，`docker-compose` 的安装超出了本文档的范围。要安装`docker-compose` 本身， 请按照官方的 [安装说明](https://docs.docker.com/compose/install/)进行操作。
## 基础设置
最简单的设置只需创建一个卷和一个网络，并将 `gitea/gitea:latest-rootless` 镜像作为服务启动。由于没有可用的数据库，可以使用 SQLite3 来初始化一个。
创建一个名为 `data` 和 `config`:
```sh
mkdir -p gitea/{data,config}
cd gitea
touch docker-compose.yml
```
然后将以下内容粘贴到名为 `docker-compose.yml` 的文件中：
```yaml
version: "2"
services:
server:
image: gitea/gitea:{{< version >}}-rootless
restart: always
volumes:
- ./data:/var/lib/gitea
- ./config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "2222:2222"
```
请注意，卷应由在配置文件中指定的UID/GID的用户/组所有。默认情况下，Docker中的Gitea将使用uid:1000 gid:1000。如果需要，您可以使用以下命令设置这些文件夹的所有权：
```sh
sudo chown 1000:1000 config/ data/
```
> 如果未为卷设置正确的权限，容器可能无法启动。
对于稳定版本，您可以使用 `:latest-rootless`、`:1-rootless`，或指定特定的版本，如: `{{< version >}}-rootless`。如果您想使用最新的开发版本，则可以使用 `:dev-rootless` 标签。如果您想运行发布分支的最新提交，可以使用 `:1.x-dev-rootless` 标签，其中 x是 Gitea 的次要版本号（例如:`1.16-dev-rootless`）。
## 自定义端口
要将集成的SSH和Web服务器绑定到不同的端口，请调整端口部分。通常只需更改主机端口并保持容器内的端口不变。
```diff
version: "2"
services:
server:
image: gitea/gitea:{{< version >}}-rootless
restart: always
volumes:
- ./data:/var/lib/gitea
- ./config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- - "3000:3000"
- - "2222:2222"
+ - "80:3000"
+ - "22:2222"
```
## MySQL 数据库
要将 Gitea 与 MySQL 数据库结合使用，请对上面创建的 `docker-compose.yml` 文件进行以下更改。
```diff
version: "2"
services:
server:
image: gitea/gitea:{{< version >}}-rootless
+ environment:
+ - GITEA__database__DB_TYPE=mysql
+ - GITEA__database__HOST=db:3306
+ - GITEA__database__NAME=gitea
+ - GITEA__database__USER=gitea
+ - GITEA__database__PASSWD=gitea
restart: always
volumes:
- ./data:/var/lib/gitea
- ./config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "222:22"
+ depends_on:
+ - db
+
+ db:
+ image: mysql:8
+ restart: always
+ environment:
+ - MYSQL_ROOT_PASSWORD=gitea
+ - MYSQL_USER=gitea
+ - MYSQL_PASSWORD=gitea
+ - MYSQL_DATABASE=gitea
+ volumes:
+ - ./mysql:/var/lib/mysql
```
## PostgreSQL 数据库
要将 Gitea 与 PostgreSQL 数据库结合使用，请对上面创建的 `docker-compose.yml` 文件进行以下更改。
```diff
version: "2"
services:
server:
image: gitea/gitea:{{< version >}}-rootless
environment:
+ - GITEA__database__DB_TYPE=postgres
+ - GITEA__database__HOST=db:5432
+ - GITEA__database__NAME=gitea
+ - GITEA__database__USER=gitea
+ - GITEA__database__PASSWD=gitea
restart: always
volumes:
- ./data:/var/lib/gitea
- ./config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "2222:2222"
+ depends_on:
+ - db
+
+ db:
+ image: postgres:14
+ restart: always
+ environment:
+ - POSTGRES_USER=gitea
+ - POSTGRES_PASSWORD=gitea
+ - POSTGRES_DB=gitea
+ volumes:
+ - ./postgres:/var/lib/postgresql/data
```
## 命名卷 (Named Volumes)
要使用命名卷 (Named Volumes) 而不是主机卷 (Host Volumes)，请在 `docker-compose.yml` 配置中定义和使用命名卷。这样的更改将自动创建所需的卷。您不需要担心权限问题，Docker 会自动处理。
```diff
version: "2"
+volumes:
+ gitea-data:
+ driver: local
+ gitea-config:
+ driver: local
+
services:
server:
image: gitea/gitea:{{< version >}}-rootless
restart: always
volumes:
- - ./data:/var/lib/gitea
+ - gitea-data:/var/lib/gitea
- - ./config:/etc/gitea
+ - gitea-config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "2222:2222"
```
MySQL 或 PostgreSQL 容器需要单独创建。
## 自定义用户
你可以选择使用自定义用户 (遵循 --user 标志定义 https://docs.docker.com/engine/reference/run/#user)。
例如，要克隆主机用户 `git` 的定义，请使用命令 `id -u git` 并将其添加到 `docker-compose.yml` 文件中：
请确用户对保挂载的文件夹具有写权限。
```diff
version: "2"
services:
server:
image: gitea/gitea:{{< version >}}-rootless
restart: always
+ user: 1001
volumes:
- ./data:/var/lib/gitea
- ./config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "2222:2222"
```
## 启动
要启动基于 `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://<服务器-IP>:3000` 并按照安装向导进行操作。如果数据库是使用上述文档中的 `docker-compose` 设置启动的，请注意必须使用 `db` 作为数据库主机名。
# 自定义
自定义文件的位置位于 `/var/lib/gitea/custom` 目录中，可以在这里找到有关自定义的文件说明。如果使用主机卷（host volumes），很容易访问这些文件；如果使用命名卷（named volumes），则可以通过另一个容器或直接访问 `/var/lib/docker/volumes/gitea_gitea/_/var_lib_gitea` 来进行访问。在安装后，配置文件将保存在 `/etc/gitea/app.ini` 中。
# 升级
:exclamation::exclamation: **确保您已将数据卷迁移到 Docker 容器之外的其他位置** :exclamation::exclamation:
要将安装升级到最新版本，请按照以下步骤操作：
```
# 如果在 docker-compose.yml 中指定了版本，请编辑该文件以更新版本
# 拉取新的镜像
docker-compose pull
# 启动一个新的容器，自动移除旧的容器
docker-compose up -d
```
# 从标准镜像升级
- 备份您的设置
- 将卷挂载点从 `/data` 更改为 `/var/lib/gitea`
- 如果使用了自定义的 `app.ini`，请将其移动到新的挂载到 `/etc/gitea` 的卷中
- 将卷中的文件夹（gitea）重命名为 custom
- 如果需要，编辑 `app.ini`
- 设置 `START_SSH_SERVER = true`
- 使用镜像 `gitea/gitea:{{< version >}}-rootless`
## 使用环境变量管理部署
除了上述的环境变量外，`app.ini` 中的任何设置都可以通过形式为 `GITEA__SECTION_NAME__KEY_NAME` 的环境变量进行设置或覆盖。这些设置在每次 Docker 容器启动时都会生效。完整信息请参考[这里](https://github.com/go-gitea/gitea/tree/main/contrib/environment-to-ini).
这些环境变量可以在 `docker-compose.yml` 中传递给 Docker 容器。以下示例将启用 SMTP 邮件服务器，如果主机上设置了所需的环境变量 GITEA__mailer__FROM、GITEA__mailer__HOST、GITEA__mailer__PASSWD，或者在与 `docker-compose.yml` 相同目录中的 `.env` 文件中设置了这些环境变量：
```bash
...
services:
server:
environment:
- GITEA__mailer__ENABLED=true
- GITEA__mailer__FROM=${GITEA__mailer__FROM:?GITEA__mailer__FROM not set}
- GITEA__mailer__MAILER_TYPE=smtp
- GITEA__mailer__HOST=${GITEA__mailer__HOST:?GITEA__mailer__HOST not set}
- GITEA__mailer__IS_TLS_ENABLED=true
- GITEA__mailer__USER=${GITEA__mailer__USER:-apikey}
- GITEA__mailer__PASSWD="""${GITEA__mailer__PASSWD:?GITEA__mailer__PASSWD not set}"""
```
要设置所需的 TOKEN 和 SECRET 值，可以使用 Gitea 的内置[生成使用函数](https://docs.gitea.io/en-us/command-line/#generate).
# SSH 容器透传
由于 SSH 在容器内运行，如果需要 SSH 支持，需要将 SSH 从主机透传到容器。一种选择是在容器内运行 SSH，并使用非标准端口（或将主机端口移动到非标准端口）。另一种可能更直接的选择是将主机上的 SSH 命令转发到容器。下面解释了这种设置。
本指南假设您已在主机上创建了一个名为 `git` 的用户，并具有运行 `docker exec` 的权限，并且 Gitea 容器的名称为 `gitea`。您需要修改该用户的 shell，以将命令转发到容器内的 `sh` 可执行文件，使用 `docker exec`。
首先，在主机上创建文件 `/usr/local/bin/gitea-shell`，并填入以下内容：
```bash
#!/bin/sh
/usr/bin/docker exec -i --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
```
注意上述 docker 命令中的 `gitea` 是容器的名称。如果您的容器名称不同，请记得更改。
还应确保正确设置了 shell 包装器的权限：
```bash
sudo chmod +x /usr/local/bin/gitea-shell
```
一旦包装器就位，您可以将其设置为 `git` 用户的 shell：
```bash
sudo usermod -s /usr/local/bin/gitea-shell git
```
现在，所有的 SSH 命令都会被转发到容器，您需要在主机上设置 SSH 认证。这可以通过利用 [SSH AuthorizedKeysCommand](https://docs.gitea.io/en-us/command-line/#keys) 来匹配 Gitea 接受的密钥。在主机的 `/etc/ssh/sshd_config` 文件中添加以下代码块：
```bash
Match User git
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /usr/bin/docker exec -i gitea /usr/local/bin/gitea keys -c /etc/gitea/app.ini -e git -u %u -t %t -k %k
```
（从 1.16.0 开始，您将不需要设置 `-c /etc/gitea/app.ini` 选项。）
剩下的就是重新启动 SSH 服务器：
```bash
sudo systemctl restart sshd
```
**注意**
这实际上并没有使用 Docker 的 SSH，而是仅仅使用了围绕它的命令。
从理论上讲，您可以不运行内部的 SSH 服务器。

2
docs/content/doc/usage/actions/act-runner.en-us.md
View File

@ -1,7 +1,7 @@
---
date: "2023-04-27T15:00:00+08:00"
title: "Act Runner"
slug: "usage/actions/act-runner"
slug: "act-runner"
weight: 20
draft: false
toc: false

203
docs/content/doc/usage/actions/act-runner.zh-cn.md Normal file
View File

@ -0,0 +1,203 @@
---
date: "2023-05-24T15:00:00+08:00"
title: "Act Runner"
slug: "act-runner"
weight: 20
draft: false
toc: false
menu:
sidebar:
parent: "actions"
name: "Act Runner"
weight: 20
identifier: "actions-runner"
---
# Act Runner
本页面将详细介绍[Act Runner](https://gitea.com/gitea/act_runner)，这是Gitea Actions的Runner。
**目录**
{{< toc >}}
## 要求
建议在Docker容器中运行Job，因此您需要首先安装Docker。
并确保Docker守护进程正在运行。
其他与Docker API兼容的OCI容器引擎也应该可以正常工作，但尚未经过测试。
但是，如果您确定要直接在主机上运行Job，则不需要Docker。
## 安装
有多种安装Act Runner的方法。
### 下载二进制文件
您可以从[发布页面](https://gitea.com/gitea/act_runner/releases)下载二进制文件。
然而，如果您想使用最新的夜间构建版本，可以从[下载页面](https://dl.gitea.com/act_runner/)下载。
下载二进制文件时，请确保您已经下载了适用于您的平台的正确版本。
您可以通过运行以下命令进行检查：
```bash
chmod +x act_runner
./act_runner --version
```
如果看到版本信息，则表示您已经下载了正确的二进制文件。
### 使用 Docker 镜像
您可以使用[docker hub](https://hub.docker.com/r/gitea/act_runner/tags)上的Docker镜像。
与二进制文件类似，您可以使用`nightly`标签使用最新的夜间构建版本，而`latest`标签是最新的稳定版本。
```bash
docker pull gitea/act_runner:latest # for the latest stable release
docker pull gitea/act_runner:nightly # for the latest nightly build
```
## 配置
配置通过配置文件进行。它是可选的，当没有指定配置文件时，将使用默认配置。
您可以通过运行以下命令生成配置文件：
```bash
./act_runner generate-config
```
默认配置是安全的，可以直接使用。
```bash
./act_runner generate-config > config.yaml
./act_runner --config config.yaml [command]
```
当使用Docker镜像时，可以使用`CONFIG_FILE`环境变量指定配置文件。确保将文件作为卷挂载到容器中：
```bash
docker run -v $(pwd)/config.yaml:/config.yaml -e CONFIG_FILE=/config.yaml ...
```
您可能注意到上面的命令都是不完整的，因为现在还不是运行Act Runner的时候。
在运行Act Runner之前，我们需要首先将其注册到您的Gitea实例中。
## 注册
在运行Act Runner之前，需要进行注册，因为Runner需要知道从哪里获取Job，并且对于Gitea实例来说，识别Runner也很重要。
### Runner级别
您可以在不同级别上注册Runner，它可以是：
- 实例级别：Runner将为实例中的所有存储库运行Job。
- 组织级别：Runner将为组织中的所有存储库运行Job。
- 存储库级别：Runner将为其所属的存储库运行Job。
请注意，即使存储库具有自己的存储库级别Runner，它仍然可以使用实例级别或组织级别Runner。未来的版本可能提供更多对此进行更好控制的选项。
### 获取注册令牌
Runner级别决定了从哪里获取注册令牌。
- 实例级别：管理员设置页面，例如 `<your_gitea.com>/admin/runners`。
- 组织级别：组织设置页面，例如 `<your_gitea.com>/<org>/settings/runners`。
- 存储库级别：存储库设置页面，例如 `<your_gitea.com>/<owner>/<repo>/settings/runners`。
如果您无法看到设置页面，请确保您具有正确的权限并且已启用 Actions。
注册令牌的格式是一个随机字符串 `D0gvfu2iHfUjNqCYVljVyRV14fISpJxxxxxxxxxx`。
### 注册Runner
可以通过运行以下命令来注册Act Runner：
```bash
./act_runner register
```
或者，您可以使用 `--config` 选项来指定前面部分提到的配置文件。
```bash
./act_runner --config config.yaml register
```
您将逐步输入注册信息，包括：
- Gitea 实例的 URL，例如 `https://gitea.com/` 或 `http://192.168.8.8:3000/`。
- 注册令牌。
- Runner名称（可选）。如果留空，将使用主机名。
- Runner标签（可选）。如果留空，将使用默认标签。
您可能对Runner标签感到困惑，稍后将对其进行解释。
如果您想以非交互方式注册Runner，可以使用参数执行以下操作。
```bash
./act_runner register --no-interactive --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
```
注册Runner后，您可以在当前目录中找到一个名为 `.runner` 的新文件。该文件存储注册信息。
请不要手动编辑该文件。
如果此文件丢失或损坏，可以直接删除它并重新注册。
如果您想将注册信息存储在其他位置，请在配置文件中指定，并不要忘记指定 `--config` 选项。
### 使用Docker注册Runner
如果您使用的是Docker镜像，注册行为会略有不同。在这种情况下，注册和运行合并为一步，因此您需要在运行Act Runner时指定注册信息。
```bash
docker run \
-v $(pwd)/config.yaml:/config.yaml \
-v $(pwd)/data:/data \
-v /var/run/docker.sock:/var/run/docker.sock \
-e CONFIG_FILE=/config.yaml \
-e GITEA_INSTANCE_URL=<instance_url> \
-e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
-e GITEA_RUNNER_NAME=<runner_name> \
-e GITEA_RUNNER_LABELS=<runner_labels> \
--name my_runner \
-d gitea/act_runner:nightly
```
您可能注意到我们已将`/var/run/docker.sock`挂载到容器中。
这是因为Act Runner将在Docker容器中运行Job，因此它需要与Docker守护进程进行通信。
如前所述，如果要在主机上直接运行Job，可以将其移除。
需要明确的是，这里的 "主机" 实际上指的是当前运行 Act Runner的容器，而不是主机机器本身。
### 标签
Runner的标签用于确定Runner可以运行哪些Job以及如何运行它们。
默认标签为`ubuntu-latest:docker://node:16-bullseye,ubuntu-22.04:docker://node:16-bullseye,ubuntu-20.04:docker://node:16-bullseye,ubuntu-18.04:docker://node:16-buster`。
它们是逗号分隔的列表，每个项目都是一个标签。
让我们以 `ubuntu-22.04:docker://node:16-bullseye` 为例。
它意味着Runner可以运行带有`runs-on: ubuntu-22.04`的Job，并且该Job将在使用`node:16-bullseye`镜像的Docker容器中运行。
如果默认镜像无法满足您的需求，并且您有足够的磁盘空间可以使用更好、更大的镜像，您可以将其更改为`ubuntu-22.04:docker://<您喜欢的镜像>`。
您可以在[act 镜像](https://github.com/nektos/act/blob/master/IMAGES.md)上找到更多有用的镜像。
如果您想直接在主机上运行Job，您可以将其更改为`ubuntu-22.04:host`或仅`ubuntu-22.04`，`:host`是可选的。
然而，我们建议您使用类似`linux_amd64:host`或`windows:host`的特殊名称，以避免误用。
还有一点需要注意的是，建议在更改标签时注册Runner。
这可能会有些麻烦，所以我们可能会在将来提供更好的方法来处理。
## 运行
注册完Runner后，您可以通过运行以下命令来运行它：
```bash
./act_runner daemon
# or
./act_runner daemon --config config.yaml
```
Runner将从Gitea实例获取Job并自动运行它们。
由于Act Runner仍处于开发中，建议定期检查最新版本并进行升级。

2
docs/content/doc/usage/actions/comparison.en-us.md
View File

@ -1,7 +1,7 @@
---
date: "2023-04-27T15:00:00+08:00"
title: "Compared to GitHub Actions"
slug: "usage/actions/comparison"
slug: "comparison"
weight: 30
draft: false
toc: false

171
docs/content/doc/usage/actions/comparison.zh-cn.md Normal file
View File

@ -0,0 +1,171 @@
---
date: "2023-05-24T15:00:00+08:00"
title: "与GitHub Actions的对比"
slug: "comparison"
weight: 30
draft: false
toc: false
menu:
sidebar:
parent: "actions"
name: "对比"
weight: 30
identifier: "actions-comparison"
---
# 与GitHub Actions的对比
尽管Gitea Actions旨在与GitHub Actions兼容，但它们之间存在一些差异。
**目录**
{{< toc >}}
## 额外功能
### Action URL绝对路径
Gitea Actions支持通过URL绝对路径定义actions，这意味着您可以使用来自任何Git存储库的Actions。
例如，`uses: https://github.com/actions/checkout@v3`或`uses: http://your_gitea.com/owner/repo@branch`。
### 使用Go编写Actions
Gitea Actions支持使用Go编写Actions。
请参阅[创建Go Actions](https://blog.gitea.io/2023/04/creating-go-actions/)。
## 不支持的工作流语法
### `concurrency`
这是用于一次运行一个Job。
请参阅[使用并发](https://docs.github.com/zh/actions/using-jobs/using-concurrency)。
Gitea Actions目前不支持此功能。
### `run-name`
这是工作流生成的工作流运行的名称。
请参阅[GitHub Actions 的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#run-name)。
Gitea Actions目前不支持此功能。
### `permissions`和`jobs.<job_id>.permissions`
请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#permissions)。
Gitea Actions目前不支持此功能。
### `jobs.<job_id>.timeout-minutes`
请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes)。
Gitea Actions目前不支持此功能。
### `jobs.<job_id>.continue-on-error`
请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idcontinue-on-error)。
Gitea Actions目前不支持此功能。
### `jobs.<job_id>.environment`
请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment)。
Gitea Actions 目前不支持此功能。
### 复杂的`runs-on`
请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)。
Gitea Actions目前只支持`runs-on: xyz`或`runs-on: [xyz]`。
### `workflow_dispatch`
请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#onworkflow_dispatch)。
Gitea Actions目前不支持此功能。
### `hashFiles`表达式
请参阅[表达式](https://docs.github.com/en/actions/learn-github-actions/expressions#hashfiles)。
Gitea Actions目前不支持此功能，如果使用它，结果将始终为空字符串。
作为解决方法，您可以使用[go-hashfiles](https://gitea.com/actions/go-hashfiles)。
## 缺失的功能
### 变量
请参阅[变量](https://docs.github.com/zh/actions/learn-github-actions/variables)。
目前变量功能正在开发中。
### 问题匹配器
问题匹配器是一种扫描Actions输出以查找指定正则表达式模式并在用户界面中突出显示该信息的方法。
请参阅[问题匹配器](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md)。
Gitea Actions目前不支持此功能。
### 为错误创建注释
请参阅[为错误创建注释](https://docs.github.com/zh/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error)。
Gitea Actions目前不支持此功能。
## 缺失的UI功能
### 预处理和后处理步骤
预处理和后处理步骤在Job日志用户界面中没有自己的用户界面。
## 不一样的行为
### 下载Actions
Gitea Actions默认不从GitHub下载Actions。
"默认" 意味着您在`uses` 字段中不指定主机，如`uses: actions/checkout@v3`。
相反，`uses: https://github.com/actions/checkout@v3`是有指定主机的。
如果您不进行配置，缺失的主机将填充为`https://gitea.com`。
这意味着`uses: actions/checkout@v3`将从[gitea.com/actions/checkout](https://gitea.com/actions/checkout)下载该Action，而不是[github.com/actions/checkout](https://github.com/actions/checkout)。
正如前面提到的，这是可配置的。
如果您希望您的运行程序默认从GitHub或您自己的Gitea实例下载动作，您可以通过设置`[actions].DEFAULT_ACTIONS_URL`进行配置。请参阅[配置备忘单]({{< relref "doc/administration/config-cheat-sheet.zh-cn.md#actions-actions" >}})。
### 上下文可用性
不检查上下文可用性，因此您可以在更多地方使用env上下文。
请参阅[上下文可用性](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability)。
## 已知问题
### `docker/build-push-action@v4`
请参阅[act_runner#119](https://gitea.com/gitea/act_runner/issues/119#issuecomment-738294)。
`ACTIONS_RUNTIME_TOKEN`在Gitea Actions中是一个随机字符串，而不是JWT。
但是`DOCKER/BUILD-PUSH-ACTION@V4尝试将令牌解析为JWT，并且不处理错误，因此Job失败。
有两种解决方法：
手动将`ACTIONS_RUNTIME_TOKEN`设置为空字符串，例如：
``` yml
- name: Build and push
uses: docker/build-push-action@v4
env:
ACTIONS_RUNTIME_TOKEN: ''
with:
...
```
该问题已在较新的[提交](https://gitea.com/docker/build-push-action/commit/d8823bfaed2a82c6f5d4799a2f8e86173c461aba?style=split&whitespace=show-all#diff-1af9a5bdf96ddff3a2f3427ed520b7005e9564ad)中修复，但尚未发布。因此，您可以通过指定分支名称来使用最新版本，例如：
``` yml
- name: Build and push
uses: docker/build-push-action@master
with:
...
```

2
docs/content/doc/usage/actions/design.en-us.md
View File

@ -1,7 +1,7 @@
---
date: "2023-04-27T15:00:00+08:00"
title: "Design of Gitea Actions"
slug: "usage/actions/design"
slug: "design"
weight: 40
draft: false
toc: false

136
docs/content/doc/usage/actions/design.zh-cn.md Normal file
View File

@ -0,0 +1,136 @@
---
date: "2023-05-24T15:00:00+08:00"
title: "Gitea Actions设计"
slug: "design"
weight: 40
draft: false
toc: false
menu:
sidebar:
parent: "actions"
name: "设计"
weight: 40
identifier: "actions-design"
---
# Gitea Actions设计
Gitea Actions由多个组件组成。本文档将对它们进行逐个描述。
**目录**
{{< toc >}}
## Act
[nektos/act](https://github.com/nektos/act) 项目是一个优秀的工具，允许你在本地运行GitHub Actions。
我们受到了它的启发，并思考它是否可能为Gitea运行Actions。
然而，尽管[nektos/act](https://github.com/nektos/act)被设计为一个命令行工具，但我们实际上需要的是一个专为Gitea修改的Go库。
因此，我们在[gitea/act](https://gitea.com/gitea/act)基础上进行了分叉。
这是一个软分叉，将定期跟进上游。
虽然添加了一些自定义提交，但我们会尽力避免对原始代码进行太多更改。
分叉的 act 只是Gitea特定用途的桥接或适配器。
还添加了一些额外的提交，例如：
- 将执行日志输出到日志记录器钩子，以便报告给Gitea
- 禁用 GraphQL URL，因为Gitea不支持它
- 每个Job启动一个新的容器，而不是重复使用，以确保隔离性。
这些修改没有理由合并到上游。
如果用户只想在本地运行可信的Actions，它们是没有意义的。
然而，将来可能会出现重叠，例如两个项目都需要的必要错误修复或新功能。
在这些情况下，我们将向上游仓库贡献变更。
## act runner
Gitea的Runner被称为act runner，因为它基于act。
与其他CIRunner一样，我们将其设计为Gitea的外部部分，这意味着它应该在与Gitea不同的服务器上运行。
为了确保Runner连接到正确的Gitea实例，我们需要使用令牌注册它。
此外，Runner通过声明自己的标签向Gitea报告它可以运行的Job类型。
之前，我们提到工作流文件中的 `runs-on: ubuntu-latest` 表示该Job将在具有`ubuntu-latest`标签的Runner上运行。
但是，Runner如何知道要运行 `ubuntu-latest`？答案在于将标签映射到环境。
这就是为什么在注册过程中添加自定义标签时，需要输入一些复杂内容，比如`my_custom_label:docker://centos:7`。
这意味着Runner可以接受需要在`my_custom_label`上运行的Job，并通过使用`centos:7`镜像的Docker容器来运行它。
然而，Docker不是唯一的选择。
act 也支持直接在主机上运行Job。
这是通过像`linux_arm:host`这样的标签实现的。
这个标签表示Runner可以接受需要在`linux_arm`上运行的Job，并直接在主机上运行它们。
标签的设计遵循格式`label[:schema[:args]]`。
如果省略了schema，则默认为`host`。
因此，
- `my_custom_label:docker://node:18`：使用`node:18 Docker`镜像运行带有`my_custom_label`标签的Job。
- `my_custom_label:host`：在主机上直接运行带有`my_custom_label`标签的Job。
- `my_custom_label`：等同于`my_custom_label:host`。
- `my_custom_label:vm:ubuntu-latest`：（仅为示例，未实现）使用带有`ubuntu-latest` ISO的虚拟机运行带有`my_custom_label`标签的Job。
## 通信协议
由于act runner是Gitea的独立部分，我们需要一种协议让Runner与Gitea实例进行通信。
然而，我们不认为让Gitea监听一个新端口是个好主意。
相反，我们希望重用HTTP端口，这意味着我们需要一个与HTTP兼容的协议。
因此，我们选择使用基于HTTP的gRPC。
我们使用[actions-proto-def](https://gitea.com/gitea/actions-proto-def) 和 [actions-proto-go](https://gitea.com/gitea/actions-proto-go) 进行连接。
有关 gRPC 的更多信息，请访问[其官方网站](https://grpc.io/)。
## 网络架构
让我们来看一下整体的网络架构。
这将帮助您解决一些问题，并解释为什么使用回环地址注册Runner是个不好的主意。
![network](/images/usage/actions/network.png)
图片中标记了四个网络连接，并且箭头的方向表示建立连接的方向。
### 连接 1，act runner到Gitea实例
act runner 必须能够连接到Gitea以接收任务并发送执行结果回来。
### 连接 2，Job容器到Gitea实例
即使Job容器位于同一台机器上，它们的网络命名空间与Runner不同。
举个例子，如果工作流中包含 `actions/checkout@v3`，Job容器需要连接到Gitea来获取代码。
获取代码并不总是运行某些Job所必需的，但在大多数情况下是必需的。
如果您使用回环地址注册Runner，当Runner与Gitea在同一台机器上时，Runner可以连接到Gitea。
然而，如果Job容器尝试从本地主机获取代码，它将失败，因为Gitea不在同一个容器中。
### 连接 3，act runner到互联网
当您使用诸如 `actions/checkout@v3` 的一些Actions时，act runner下载的是脚本，而不是Job容器。
默认情况下，它从[gitea.com](http://gitea.com/)下载，因此需要访问互联网。
它还默认从Docker Hub下载一些Docker镜像，这也需要互联网访问。
然而，互联网访问并不是绝对必需的。
您可以配置您的Gitea实例从您的内部网络设施中获取 Actions 或镜像。
实际上，您的Gitea实例可以同时充当 Actions 市场和镜像注册表。
您可以将GitHub上的Actions仓库镜像到您的Gitea实例，并将其用作普通Actions。
而 [Gitea 容器注册表](https://docs.gitea.io/en-us/usage/packages/container/) 可用作Docker镜像注册表。
### 连接 4，Job容器到互联网
当使用诸如`actions/setup-go@v4`的Actions时，可能需要从互联网下载资源，以设置Job容器中的Go语言环境。
因此，成功完成这些Actions需要访问互联网。
然而，这也是可选的。
您可以使用自定义的Actions来避免依赖互联网访问，或者可以使用已安装所有依赖项的打包的Docker镜像来运行Job。
## 总结
使用Gitea Actions只需要确保Runner能够连接到Gitea实例。
互联网访问是可选的，但如果没有互联网访问，将需要额外的工作。
换句话说：当Runner能够自行查询互联网时，它的工作效果最好，但您不需要将其暴露给互联网（无论是单向还是双向）。
如果您在使用Gitea Actions时遇到任何网络问题，希望上面的图片能够帮助您进行故障排除。

2
docs/content/doc/usage/actions/faq.en-us.md
View File

@ -1,7 +1,7 @@
---
date: "2023-04-27T15:00:00+08:00"
title: "Frequently Asked Questions of Gitea Actions"
slug: "usage/actions/faq"
slug: "faq"
weight: 100
draft: false
toc: false

166
docs/content/doc/usage/actions/faq.zh-cn.md Normal file
View File

@ -0,0 +1,166 @@
---
date: "2023-05-24T15:00:00+08:00"
title: "Gitea Actions常见问题解答"
slug: "faq"
weight: 100
draft: false
toc: false
menu:
sidebar:
parent: "actions"
name: "常见问题"
weight: 100
identifier: "actions-faq"
---
# Gitea Actions常见问题解答
本页面包含一些关于Gitea Actions的常见问题和答案。
**目录**
{{< toc >}}
## 为什么默认情况下不启用Actions？
我们知道为整个实例和每个仓库启用Actions可能很麻烦，但并不是每个人都喜欢或需要此功能。
在我们认为Gitea Actions值得被特别对待之前，我们认为还需要做更多的工作来改进它。
## 是否可以在我的实例中默认启用新仓库的Actions？
是的，当您为实例启用Actions时，您可以选择默认启用actions单元以适用于所有新仓库。
```ini
[repository]
DEFAULT_REPO_UNITS = ...,repo.actions
```
## 在工作流文件中应该使用`${{ github.xyz }}`还是`${{ gitea.xyz }}`？
您可以使用`github.xyz`，Gitea将正常工作。
如前所述，Gitea Actions的设计是与GitHub Actions兼容的。
然而，我们建议在工作流文件中使用`gitea.xyz`，以防止在工作流文件中出现不同类型的密钥（因为您在Gitea上使用此工作流，而不是GitHub）。
不过，这完全是可选的，因为目前这两个选项的效果是相同的。
## 是否可以为特定用户（而不是组织）注册Runner？
目前还不可以。
从技术上讲是可以实现的，但我们需要讨论是否有必要。
## 使用`actions/checkout@v3`等Actions时，Job容器会从何处下载脚本？
您可能知道GitHub上有成千上万个[Actions市场](https://github.com/marketplace?type=actions)。
然而，当您编写`uses: actions/checkout@v3`时，它实际上默认从[gitea.com/actions/checkout](http://gitea.com/actions/checkout)下载脚本（而不是从GitHub下载）。
这是[github.com/actions/checkout](http://github.com/actions/checkout)的镜像，但无法将它们全部镜像。
这就是为什么在尝试使用尚未镜像的某些Actions时可能会遇到失败的原因。
好消息是，您可以指定要从任何位置使用Actions的URL前缀。
这是Gitea Actions中的额外语法。
例如：
- `uses: https://github.com/xxx/xxx@xxx`
- `uses: https://gitea.com/xxx/xxx@xxx`
- `uses: http://your_gitea_instance.com/xxx@xxx`
注意，`https://`或`http://`前缀是必需的！
另外，如果您希望您的Runner默认从GitHub或您自己的Gitea实例下载Actions，可以通过设置 `[actions].DEFAULT_ACTIONS_URL`进行配置。
参见[配置速查表](https://docs.gitea.io/en-us/config-cheat-sheet/#actions-actions)。
这是与GitHub Actions的一个区别，但它应该允许用户以更灵活的方式运行Actions。
## 如何限制Runner的权限？
Runner仅具有连接到您的Gitea实例的权限。
当任何Runner接收到要运行的Job时，它将临时获得与Job关联的仓库的有限权限。
如果您想为Runner提供更多权限，允许它访问更多私有仓库或外部系统，您可以向其传递[密钥](https://docs.gitea.io/en-us/usage/secrets/)。
对于 Actions 的细粒度权限控制是一项复杂的工作。
在未来，我们将添加更多选项以使Gitea更可配置，例如允许对仓库进行更多写访问或对同一组织中的所有仓库进行读访问。
## 如何避免被黑客攻击？
有两种可能的攻击类型：未知的Runner窃取您的仓库中的代码或密钥，或恶意脚本控制您的Runner。
避免前者意味着不允许您不认识的人为您的仓库、组织或实例注册Runner。
后者要复杂一些。
如果您为公司使用私有的Gitea实例，您可能不需要担心安全问题，因为您信任您的同事，并且可以追究他们的责任。
对于公共实例，情况略有不同。
以下是我们在 [gitea.com](http://gitea.com/)上的做法：
- 我们仅为 "gitea" 组织注册Runner，因此我们的Runner不会执行来自其他仓库的Job。
- 我们的Runner始终在隔离容器中运行Job。虽然可以直接在主机上进行这样的操作，但出于安全考虑，我们选择不这样做。
- 对于 fork 的拉取请求，需要获得批准才能运行Actions。参见[#22803](https://github.com/go-gitea/gitea/pull/22803)。
- 如果有人在[gitea.com](http://gitea.com/)为其仓库或组织注册自己的Runner，我们不会反对，只是不会在我们的组织中使用它。然而，他们应该注意确保该Runner不被他们不认识的其他用户使用。
## act runner支持哪些操作系统？
它在Linux、macOS和Windows上运行良好。
虽然理论上支持其他操作系统，但需要进一步测试。
需要注意的一点是，如果选择直接在主机上运行Job而不是在Job容器中运行，操作系统之间的环境差异可能会导致意外的失败。
例如，在大多数情况下，Windows上没有可用的bash，而act尝试默认使用bash运行脚本。
因此，您需要在工作流文件中将默认shell指定为`powershell`，参考[defaults.run](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun)。
```yaml
defaults:
run:
shell: powershell
```
## 为什么选择GitHub Actions？为什么不选择与GitLab CI/CD兼容的工具？
[@lunny](https://gitea.com/lunny)在实现Actions的[问题](https://github.com/go-gitea/gitea/issues/13539)中已经解释过这个问题。
此外，Actions不仅是一个CI/CD 系统，还是一个自动化工具。
在开源世界中，已经有许多[市场上的Actions](https://github.com/marketplace?type=actions)实现了。
能够重用它们是令人兴奋的。
## 如果它在多个标签上运行，例如 `runs-on: [label_a, label_b]`，会发生什么？
这是有效的语法。
它意味着它应该在具有`label_a` **和** `label_b`标签的Runner上运行，参考[GitHub Actions的工作流语法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)。
不幸的是，act runner 并不支持这种方式。
如上所述，我们将标签映射到环境：
- `ubuntu` → `ubuntu:22.04`
- `centos` → `centos:8`
但我们需要将标签组映射到环境，例如：
- `[ubuntu]` → `ubuntu:22.04`
- `[with-gpu]` → `linux:with-gpu`
- `[ubuntu, with-gpu]` → `ubuntu:22.04_with-gpu`
我们还需要重新设计任务分配给Runner的方式。
具有`ubuntu`、`centos`或`with-gpu`的Runner并不一定表示它可以接受`[centos, with-gpu]`的Job。
因此，Runner应该通知Gitea实例它只能接受具有 `[ubuntu]`、`[centos]`、`[with-gpu]` 和 `[ubuntu, with-gpu]`的Job。
这不是一个技术问题，只是在早期设计中被忽视了。
参见[runtime.go#L65](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65)。
目前，act runner尝试匹配标签中的每一个，并使用找到的第一个匹配项。
## 代理标签和自定义标签对于Runner有什么区别？
![labels](/images/usage/actions/labels.png)
代理标签是由Runner在注册过程中向Gitea实例报告的。
而自定义标签则是由Gitea的管理员或组织或仓库的所有者手动添加的（取决于Runner所属的级别）。
然而，目前这方面的设计还有待改进，因为它目前存在一些不完善之处。
您可以向已注册的Runner添加自定义标签，比如 `centos`，这意味着该Runner将接收具有`runs-on: centos`的Job。
然而，Runner可能不知道要使用哪个环境来执行该标签，导致它使用默认镜像或导致逻辑死胡同。
这个默认值可能与用户的期望不符。
参见[runtime.go#L71](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71)。
与此同时，如果您想更改Runner的标签，我们建议您重新注册Runner。
## Gitea Actions runner会有更多的实现吗？
虽然我们希望提供更多的选择，但由于我们有限的人力资源，act runner将是唯一受支持的官方Runner。
然而，无论您如何决定，Gitea 和act runner都是完全开源的，所以任何人都可以创建一个新的/更好的实现。
我们支持您的选择，无论您如何决定。
如果您选择分支act runner来创建自己的版本，请在您认为您的更改对其他人也有帮助的情况下贡献这些更改。

2
docs/content/doc/usage/actions/overview.en-us.md
View File

@ -1,7 +1,7 @@
---
date: "2023-04-27T15:00:00+08:00"
title: "Gitea Actions"
slug: "usage/actions/overview"
slug: "overview"
weight: 1
draft: false
toc: false

55
docs/content/doc/usage/actions/overview.zh-cn.md Normal file
View File

@ -0,0 +1,55 @@
---
date: "2023-05-24T15:00:00+08:00"
title: "Gitea Actions"
slug: "overview"
weight: 1
draft: false
toc: false
menu:
sidebar:
parent: "actions"
name: "Overview"
weight: 1
identifier: "actions-overview"
---
# Gitea Actions
从Gitea **1.19**版本开始，Gitea Actions成为了内置的CI/CD解决方案。
**目录**
{{< toc >}}
## 名称
Gitea Actions与[GitHub Actions](https://github.com/features/actions)相似且兼容，它的名称也受到了它的启发。
为了避免混淆，在这里我们明确了拼写方式：
- "Gitea Actions"（两个单词都大写且带有"s"）是Gitea功能的名称。
- "GitHub Actions"是GitHub功能的名称。
- "Actions"根据上下文的不同可以指代以上任意一个。在本文档中指代的是"Gitea Actions"。
- "action"或"actions"指代一些要使用的脚本/插件，比如"actions/checkout@v3"或"actions/cache@v3"。
## Runner
和其他CI/CD解决方案一样，Gitea不会自己运行Job，而是将Job委托给Runner。
Gitea Actions的Runner被称为[act runner](https://gitea.com/gitea/act_runner)，它是一个独立的程序，也是用Go语言编写的。
它是基于[nektos/act](http://github.com/nektos/act)的一个[分支](https://gitea.com/gitea/act) 。
由于Runner是独立部署的，可能存在潜在的安全问题。
为了避免这些问题，请遵循两个简单的规则：
- 不要为你的仓库、组织或实例使用你不信任的Runner。
- 不要为你不信任的仓库、组织或实例提供Runner。
对于内部使用的Gitea实例，比如企业或个人使用的实例，这两个规则不是问题，它们自然而然就是如此。
然而，对于公共的Gitea实例，比如[gitea.com](https://gitea.com)，在添加或使用Runner时应当牢记这两个规则。
## 状态
Gitea Actions仍然在开发中，因此可能存在一些错误和缺失的功能。
并且在稳定版本（v1.20或更高版本）之前可能会进行一些重大的更改。
如果情况发生变化，我们将在此处进行更新。
因此，请在其他地方找到过时文章时参考此处的内容。

2
docs/content/doc/usage/actions/quickstart.en-us.md
View File

@ -1,7 +1,7 @@
---
date: "2023-04-27T15:00:00+08:00"
title: "Quick Start"
slug: "usage/actions/quickstart"
slug: "quickstart"
weight: 10
draft: false
toc: false

140
docs/content/doc/usage/actions/quickstart.zh-cn.md Normal file
View File

@ -0,0 +1,140 @@
---
date: "2023-05-24T15:00:00+08:00"
title: "快速入门"
slug: "quickstart"
weight: 10
draft: false
toc: false
menu:
sidebar:
parent: "actions"
name: "快速入门"
weight: 10
identifier: "actions-quickstart"
---
# 快速入门
本页面将指导您使用Gitea Actions的过程。
**目录**
{{< toc >}}
## 设置Gitea
首先，您需要一个Gitea实例。
您可以按照[文档]({{< relref "doc/installation/from-package.zh-cn.md" >}}) 来设置一个新实例或升级现有实例。
无论您如何安装或运行Gitea，只要版本号是1.19.0或更高即可。
默认情况下，Actions是禁用的，因此您需要将以下内容添加到配置文件中以启用它：
```ini
[actions]
ENABLED=true
```
如果您想了解更多信息或在配置过程中遇到任何问题，请参考[配置速查表]({{< relref "doc/administration/config-cheat-sheet.zh-cn.md#actions-actions" >}})。
### 设置Runner
Gitea Actions需要[act runner](https://gitea.com/gitea/act_runner) 来运行Job。
为了避免消耗过多资源并影响Gitea实例，建议您在与Gitea实例分开的机器上启动Runner。
您可以使用[预构建的二进制文件](http://dl.gitea.com/act_runner)或[容器镜像](https://hub.docker.com/r/gitea/act_runner/tags)来设置Runner。
在进一步操作之前，建议您先使用预构建的二进制文件以命令行方式运行它，以确保它与您的环境兼容，尤其是如果您在本地主机上运行Runner。
如果出现问题，这样调试起来会更容易。
该Runner可以在隔离的Docker容器中运行Job，因此您需要确保已安装Docker并且Docker守护进程正在运行。
虽然这不是严格必需的，因为Runner也可以直接在主机上运行Job，这取决于您的配置方式。
然而，建议使用Docker运行Job，因为它更安全且更易于管理。
在运行Runner之前，您需要使用以下命令将其注册到Gitea实例中：
```bash
./act_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。
您可以从 `<your_gitea.com>/admin/runners` 获取令牌。
![register runner](/images/usage/actions/register-runner.png)
注册后，当前目录中将出现一个名为 `.runner` 的新文件，该文件存储了注册信息。
请不要手动编辑该文件。
如果该文件丢失或损坏，只需删除它然后重新注册即可。
最后，是时候启动Runner了：
```bash
./act_runner daemon
```
您可以在管理页面上看到新的Runner：
![view runner](/images/usage/actions/view-runner.png)
您可以通过访问[act runner]({{< relref "doc/usage/actions/act-runner.zh-cn.md" >}}) 获取更多信息。
### 使用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@v3
- 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`。
有关更多信息，请参阅[数据库准备工作]({{< relref "doc/installation/database-preparation.zh-cn.md#mysql" >}})。
或者，您可以从演示文件中删除所有表情符号，然后再尝试一次。
`on: [push]` 这一行表示当您向该存储库推送提交时，工作流将被触发。
然而，当您上传 YAML 文件时，它也会推送一个提交，所以您应该在"Actions"标签中看到一个新的任务。
![view job](/images/usage/actions/view-job.png)
做得好！您已成功开始使用Actions。

49
docs/content/doc/usage/agit-support.zh-cn.md Normal file
View File

@ -0,0 +1,49 @@
---
date: "2023-05-23T09:00:00+08:00"
title: "Agit 设置"
slug: "agit-setup"
weight: 12
toc: false
draft: false
aliases:
- /zh-cn/agit-setup
menu:
sidebar:
parent: "usage"
name: "Agit 设置"
weight: 12
identifier: "agit-setup"
---
# Agit 设置
在 Gitea `1.13` 版本中，添加了对 [agit](https://git-repo.info/zh/2020/03/agit-flow-and-git-repo/) 的支持。
## 使用 Agit 创建 PR
Agit 允许在推送代码到远程仓库时创建 PR（合并请求）。
通过在推送时使用特定的 refspec（git 中已知的位置标识符），可以实现这一功能。
下面的示例说明了这一点：
```shell
git push origin HEAD:refs/for/master
```
该命令的结构如下：
- `HEAD`：目标分支
- `refs/<for|draft|for-review>/<branch>`：目标 PR 类型
- `for`：创建一个以 `<branch>` 为目标分支的普通 PR
- `draft`/`for-review`：目前被静默忽略
- `<branch>/<session>`：要打开 PR 的目标分支
- `-o <topic|title|description>`：PR 的选项
- `title`：PR 的标题
- `topic`：PR 应该打开的分支名称
- `description`：PR 的描述
- `force-push`：确认强制更新目标分支
下面是另一个高级示例，用于创建一个以 `topic`、`title` 和 `description` 为参数的新 PR，目标分支是 `master`：
```shell
git push origin HEAD:refs/for/master -o topic="Topic of my PR" -o title="Title of the PR" -o description="# The PR Description\nThis can be **any** markdown content.\n- [x] Ok"
```

26
docs/content/doc/usage/clone-filter.zh-cn.md Normal file
View File

@ -0,0 +1,26 @@
---
date: "2023-05-23T09:00:00+08:00"
title: "克隆过滤器 (部分克隆)"
slug: "clone-filters"
weight: 25
draft: false
toc: false
aliases:
- /zh-cn/clone-filters
menu:
sidebar:
parent: "usage"
name: "克隆过滤器"
weight: 25
identifier: "clone-filters"
---
# 克隆过滤器 (部分克隆)
Git 引入了 `--filter` 选项用于 `git clone` 命令，该选项可以过滤掉大文件和对象（如 blob），从而创建一个仓库的部分克隆。克隆过滤器对于大型仓库和/或按流量计费的连接特别有用，因为完全克隆（不使用 `--filter`）可能会很昂贵（需要下载所有历史数据）。
这需要 Git 2.22 或更高版本，无论是在 Gitea 服务器上还是在客户端上都需要如此。为了使克隆过滤器正常工作，请确保客户端上的 Git 版本至少与服务器上的版本相同（或更高）。以管理员身份登录到 Gitea，然后转到管理后台 -> 应用配置，查看服务器的 Git 版本。
默认情况下，克隆过滤器是启用的，除非在 `[git]` 下将 `DISABLE_PARTIAL_CLONE` 设置为 `true`。
请参阅 [GitHub 博客文章：了解部分克隆](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/) 以获取克隆过滤器的常见用法（无 Blob 和无树的克隆），以及 [GitLab 部分克隆文档](https://docs.gitlab.com/ee/topics/git/partial_clone.html) 以获取更高级的用法（例如按文件大小过滤和取消过滤以将部分克隆转换为完全克隆）。

50
docs/content/doc/usage/incoming-email.zh-cn.md Normal file
View File

@ -0,0 +1,50 @@
---
date: "2023-05-23T09:00:00+08:00"
title: "邮件接收"
slug: "incoming-email"
weight: 13
draft: false
toc: false
aliases:
- /zh-cn/incoming-email
menu:
sidebar:
parent: "usage"
name: "邮件接收"
weight: 13
identifier: "incoming-email"
---
# 邮件接收
Gitea 支持通过接收邮件执行多种操作。本页面描述了如何进行设置。
**目录**
{{< toc >}}
## 要求
处理接收的电子邮件需要启用 IMAP 功能的电子邮件帐户。
推荐的策略是使用 [电子邮件子地址](https://en.wikipedia.org/wiki/Email_address#Sub-addressing)，但也可以使用 catch-all 邮箱。
接收电子邮件地址中包含一个用户/操作特定的令牌，告诉 Gitea 应执行哪个操作。
此令牌应该出现在 `To` 和 `Delivered-To` 头字段中。
Gitea 会尝试检测自动回复并跳过它们，电子邮件服务器也应该配置以减少接收到的干扰（垃圾邮件、通讯订阅等）。
## 配置
要激活处理接收的电子邮件消息功能，您需要在配置文件中配置 `email.incoming` 部分。
`REPLY_TO_ADDRESS` 包含电子邮件客户端将要回复的地址。
该地址需要包含 `%{token}` 占位符，该占位符将被替换为描述用户/操作的令牌。
此占位符在地址中只能出现一次，并且必须位于地址的用户部分（`@` 之前）。
使用电子邮件子地址的示例可能如下：`incoming+%{token}@example.com`
如果使用 catch-all 邮箱，则占位符可以出现在地址的用户部分的任何位置：`incoming+%{token}@example.com`、`incoming_%{token}@example.com`、`%{token}@example.com`
## 安全性
在选择用于接收传入电子邮件的域时要小心。
建议在子域名上接收传入电子邮件，例如 `incoming.example.com`，以防止与运行在 `example.com` 上的其他服务可能存在的安全问题。

42
docs/content/doc/usage/labels.zh-cn.md Normal file
View File

@ -0,0 +1,42 @@
---
date: "2023-05-23T09:00:00+08:00"
title: "标签"
slug: "labels"
weight: 13
toc: false
draft: false
aliases:
- /zh-cn/labels
menu:
sidebar:
parent: "usage"
name: "标签"
weight: 13
identifier: "labels"
---
# 标签
您可以使用标签对工单和合并请求进行分类，并提高对它们的概览。
## 创建标签
对于仓库，可以在 `工单（Issues）` 中点击 `标签（Labels）` 来创建标签。
对于组织，您可以定义组织级别的标签，这些标签与所有组织仓库共享，包括已存在的仓库和新创建的仓库。可以在组织的 `设置（Settings）` 中创建组织级别的标签。
标签具有必填的名称和颜色，可选的描述，以及必须是独占的或非独占的（见下面的“作用域标签”）。
当您创建一个仓库时，可以通过使用 `工单标签（Issue Labels）` 选项来选择标签集。该选项列出了一些在您的实例上 [全局配置的可用标签集](../customizing-gitea/#labels)。在创建仓库时，这些标签也将被创建。
## 作用域标签
作用域标签用于确保将至多一个具有相同作用域的标签分配给工单或合并请求。例如，如果标签 `kind/bug` 和 `kind/enhancement` 的独占选项被设置，那么工单只能被分类为 bug 或 enhancement 中的一个。
作用域标签的名称必须包含 `/`（不能在名称的任一端）。标签的作用域是基于最后一个 `/` 决定的，因此例如标签 `scope/subscope/item` 的作用域是 `scope/subscope`。
## 按标签筛选
工单和合并请求列表可以按标签进行筛选。选择多个标签将显示具有所有选定标签的工单和合并请求。
通过按住 alt 键并单击标签，可以将具有所选标签的工单和合并请求从列表中排除。

156
docs/content/doc/usage/linked-references.zh-cn.md Normal file
View File

@ -0,0 +1,156 @@
---
date: "2023-05-23T09:00:00+08:00"
title: "自动链接引用"
slug: "automatically-linked-references"
weight: 15
toc: false
draft: false
aliases:
- /zh-cn/automatically-linked-references
menu:
sidebar:
parent: "usage"
name: "自动链接引用s"
weight: 15
identifier: "automatically-linked-references"
---
# 在工单、合并请求和提交消息中的自动链接引用
**目录**
{{< toc >}}
当发布工单、合并请求或评论时，文本描述会被解析以查找引用。这些引用将显示为工单视图中的链接，并且在某些情况下会触发特定的“操作”。
类似地，当列出提交消息时，它们也会被解析，并且当它们被推送到主分支时可以触发“操作”。
为了防止意外创建引用，对于引用的识别有一定的规则。例如，它们不应该包含在代码文本内部。它们还应该在周围的文本中合理清晰（例如，使用空格）。
## 用户、团队和组织提及
当找到形式为 `@username` 的文本，并且 `username` 与现有用户的名称匹配时，将创建一个“提及”引用。这将通过将文本更改为指向该用户个人资料的链接来显示，并根据被提及的用户是否具有访问内容所需的权限来可能创建通知。
示例：
> [@John](#)，你能看一下这个吗？
对于团队和组织也是有效的：
> [@Documenters](#)，我们需要为此进行规划。
> [@CoolCompanyInc](#)，这个问题关系到我们所有人！
团队将在适当时收到邮件通知，但整个组织不会收到通知。
提交消息不会产生用户通知。
## 提交
可以使用提交的 SHA1 哈希或至少七个字符的一部分来引用提交。它们将显示为指向相应提交的链接。
示例：
> 这个错误是在 [e59ff077](#) 中引入的
## 工单和合并请求
可以使用简单的符号 `#1234` 来创建对另一个工单或合并请求的引用，其中 _1234_ 是同一仓库中一个工单或合并请求的编号。这些引用将显示为指向被引用内容的链接。
创建此类型引用的效果是，在被引用的文档中创建一个“通知”，前提是引用的创建者对其具有读取权限。
示例：
> 这似乎与 [#1234](#) 相关
还可以使用形式 `owner/repository#1234` 来引用其他仓库中的工单和合并请求：
> 这似乎与 [mike/compiler#1234](#) 相关
或者也可以使用 `!1234` 符号。虽然在 Gitea 中合并请求是工单的一种形式，但 `#1234` 形式总是链接到工单；如果链接的条目恰好是一个合并请求，Gitea 会适当地进行重定向。而使用 `!1234` 符号，则会创建一个合并请求链接，根据需要会被重定向到工单。然而，如果使用外部跟踪器，这个区别可能很重要，因为工单和合并请求的链接是不能互换的。
## 可操作的引用在合并请求和提交消息中
有时，一个提交或合并请求可能会修复或重新出现在某个特定工单中。Gitea 支持在引用之前加上特定的“关键字”来关闭和重新打开被引用的工单。常见的关键字包括“closes”、“fixes”、“reopens”等。这个列表可以由站点管理员进行 [自定义]({{< ref "doc/administration/config-cheat-sheet.zh-cn.md" >}})。
示例：
> 这个合并请求 _closes_ [#1234](#)
如果可操作的引用被接受，这将在被引用的工单上创建一个通知，宣布当引用的合并请求被合并时该工单将被关闭。
为了接受可操作的引用，必须满足以下至少一项条件之一：
- 评论者在创建引用时具有关闭或重新打开工单的权限。
- 引用位于提交消息中。
- 引用作为合并请求描述的一部分发布。
在最后一种情况下，只有当合并合并请求的人具有相应权限时，工单才会被关闭或重新打开。
此外，只有合并请求和提交消息可以创建一个操作，只有工单可以通过这种方式被关闭或重新打开。
默认的关键字如下：
- **关闭工单**: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved
- **重新打开工单**: reopen, reopens, reopened
## 合并请求和提交消息中的时间跟踪
当提交或合并合并请求导致自动关闭工单时，还可以通过提交消息添加解决此工单所花费的时间。
要指定解决工单所花费的时间，需要在工单编号后面以 `@<number><time-unit>` 的格式指定时间。在一个提交消息中，可以指定多个已解决的工单，并为每个工单指定花费的时间。
支持的时间单位（`<time-unit>`）：
- `m` - 分钟
- `h` - 小时
- `d` - 天（相当于8小时）
- `w` - 周（相当于5天）
- `mo` - 月（相当于4周）
用于指定时间的数字（`<number>`）也可以是小数，例如 `@1.5h` 表示一小时半。多个时间单位可以结合使用，例如 `@1h10m` 表示1小时10分钟。
提交消息示例：
> Fixed #123 spent @1h, refs #102, fixes #124 @1.5h
这将导致工单 #123 增加 1 小时，工单 #124 增加 1 小时半。
## 外部跟踪器
Gitea 支持使用外部工单跟踪器，并可以在合并请求中创建对外部托管的工单的引用。但是，如果外部跟踪器使用数字来标识工单，那么它们将与 Gitea 中托管的合并请求无法区分。为了解决这个工单，Gitea 允许使用 `!` 标记来标识合并请求。例如：
> 这是工单 [#1234](#)，并链接到外部跟踪器。
> 这是合并请求 [!1234](#)，并链接到 Gitea 中的合并请求。
在工单和合并请求中，`!` 和 `#` 可以互换使用，除非需要进行区分。如果仓库使用外部跟踪器，默认情况下，合并提交消息将使用 `!` 作为引用。
## 工单和合并请求引用摘要
下表说明了工单和合并请求的不同类型的交叉引用。在示例中，`User1/Repo1` 指的是使用引用的仓库，而 `UserZ/RepoZ` 表示另一个仓库。
| 在 User1/Repo1 中的引用 | Repo1 的工单是外部的 | RepoZ 的工单是外部的 | 渲染效果 |
| ----------------------- | :-------------------: | :-------------------: | ------------------------------------------------ |
| `#1234` | 否 | - | 链接到 `User1/Repo1` 中的工单/合并请求 1234 |
| `!1234` | 否 | - | 链接到 `User1/Repo1` 中的工单/合并请求 1234 |
| `#1234` | 是 | - | 链接到 `User1/Repo1` 的 _外部工单_ 1234 |
| `!1234` | 是 | - | 链接到 `User1/Repo1` 的 _PR_ 1234 |
| `User1/Repo1#1234` | 否 | - | 链接到 `User1/Repo1` 中的工单/合并请求 1234 |
| `User1/Repo1!1234` | 否 | - | 链接到 `User1/Repo1` 中的工单/合并请求 1234 |
| `User1/Repo1#1234` | 是 | - | 链接到 `User1/Repo1` 的 _外部工单_ 1234 |
| `User1/Repo1!1234` | 是 | - | 链接到 `User1/Repo1` 的 _PR_ 1234 |
| `UserZ/RepoZ#1234` | - | 否 | 链接到 `UserZ/RepoZ` 中的工单/合并请求 1234 |
| `UserZ/RepoZ!1234` | - | 否 | 链接到 `UserZ/RepoZ` 中的工单/合并请求 1234 |
| `UserZ/RepoZ#1234` | - | 是 | 链接到 `UserZ/RepoZ` 的 _外部工单_ 1234 |
| `UserZ/RepoZ!1234` | - | 是 | 链接到 `UserZ/RepoZ` 的 _PR_ 1234 |
| **字母数字工单编号:** | - | - | - |
| `AAA-1234` | 是 | - | 链接到 `User1/Repo1` 的 _外部工单_ `AAA-1234` |
| `!1234` | 是 | - | 链接到 `User1/Repo1` 的 _PR_ 1234 |
| `User1/Repo1!1234` | 是 | - | 链接到 `User1/Repo1` 的 _PR_ 1234 |
| _不支持_ | - | 是 | 链接到 `UserZ/RepoZ` 的 _外部工单_ `AAA-1234` |
| `UserZ/RepoZ!1234` | - | 是 | 链接到 `UserZ/RepoZ` 中的 _PR_ 1234 |
_最后一部分适用于使用字母数字格式的外部工单跟踪器的仓库。_
_**-**: 不适用_
注意：不完全支持具有不同类型工单（外部 vs. 内部）的仓库之间的自动引用，可能会导致无效链接。

57
docs/content/doc/usage/merge-message-templates.zh-cn.md Normal file
View File

@ -0,0 +1,57 @@
---
date: "2023-05-23T09:00:00+08:00"
title: "合并消息模板"
slug: "merge-message-templates"
weight: 15
toc: false
draft: false
aliases:
- /zh-cn/merge-message-templates
menu:
sidebar:
parent: "usage"
name: "合并消息模板"
weight: 15
identifier: "merge-message-templates"
---
# 合并消息模板
**目录**
{{< toc >}}
## 文件名
PR 默认合并消息模板可能的文件名：
- `.gitea/default_merge_message/MERGE_TEMPLATE.md`
- `.gitea/default_merge_message/REBASE_TEMPLATE.md`
- `.gitea/default_merge_message/REBASE-MERGE_TEMPLATE.md`
- `.gitea/default_merge_message/SQUASH_TEMPLATE.md`
- `.gitea/default_merge_message/MANUALLY-MERGED_TEMPLATE.md`
- `.gitea/default_merge_message/REBASE-UPDATE-ONLY_TEMPLATE.md`
## 变量
您可以在这些模板中使用以下以 `${}` 包围的变量，这些变量遵循 [os.Expand](https://pkg.go.dev/os#Expand) 语法：
- BaseRepoOwnerName：此合并请求的基础仓库所有者名称
- BaseRepoName：此合并请求的基础仓库名称
- BaseBranch：此合并请求的基础仓库目标分支名称
- HeadRepoOwnerName：此合并请求的源仓库所有者名称
- HeadRepoName：此合并请求的源仓库名称
- HeadBranch：此合并请求的源仓库分支名称
- PullRequestTitle：合并请求的标题
- PullRequestDescription：合并请求的描述
- PullRequestPosterName：合并请求的提交者名称
- PullRequestIndex：合并请求的索引号
- PullRequestReference：合并请求的引用字符与索引号。例如，#1、!2
- ClosingIssues：返回一个包含将由此合并请求关闭的所有工单的字符串。例如 `close #1, close #2`
## 变基（Rebase）
在没有合并提交的情况下进行变基时，`REBASE_TEMPLATE.md` 修改最后一次提交的消息。此模板还提供以下附加变量：
- CommitTitle：提交的标题
- CommitBody：提交的正文文本

6
docs/content/doc/usage/packages/alpine.en-us.md
View File

@ -1,7 +1,7 @@
---
date: "2023-03-25T00:00:00+00:00"
title: "Alpine Packages Repository"
slug: "packages/alpine"
title: "Alpine Package Registry"
slug: "alpine"
draft: false
toc: false
menu:
@ -12,7 +12,7 @@ menu:
identifier: "alpine"
---
# Alpine Packages Repository
# Alpine Package Registry
Publish [Alpine](https://pkgs.alpinelinux.org/) packages for your user or organization.

133
docs/content/doc/usage/packages/alpine.zh-cn.md Normal file
View File

@ -0,0 +1,133 @@
---
date: "2023-03-25T00:00:00+00:00"
title: "Alpine 软件包注册表"
slug: "alpine"
draft: false
toc: false
menu:
sidebar:
parent: "packages"
name: "Alpine"
weight: 4
identifier: "alpine"
---
# Alpine 软件包注册表
在您的用户或组织中发布 [Alpine](https://pkgs.alpinelinux.org/) 软件包。
**目录**
{{< toc >}}
## 要求
要使用 Alpine 注册表，您需要使用像 curl 这样的 HTTP 客户端来上传包，并使用像 apk 这样的包管理器来消费包。
以下示例使用 `apk`。
## 配置软件包注册表
要注册 Alpine 注册表，请将 URL 添加到已知的 apk 源列表中 (`/etc/apk/repositories`):
```
https://gitea.example.com/api/packages/{owner}/alpine/<branch>/<repository>
```
| 占位符 | 描述 |
| ------------ | -------------- |
| `owner` | 软件包所有者 |
| `branch` | 要使用的分支名 |
| `repository` | 要使用的仓库名 |
如果注册表是私有的，请在 URL 中提供凭据。您可以使用密码或[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}}):
```
https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/alpine/<branch>/<repository>
```
Alpine 注册表文件使用 RSA 密钥进行签名，apk 必须知道该密钥。下载公钥并将其存储在 `/etc/apk/keys/` 目录中：
```shell
curl -JO https://gitea.example.com/api/packages/{owner}/alpine/key
```
之后，更新本地软件包索引：
```shell
apk update
```
## 发布软件包
要发布一个 Alpine 包（`*.apk`），请执行带有包内容的 HTTP `PUT` 操作，将其放在请求体中。
```
PUT https://gitea.example.com/api/packages/{owner}/alpine/{branch}/{repository}
```
| 参数 | 描述 |
| ------------ | --------------------------------------------------------------------------------------------------- |
| `owner` | 包的所有者。 |
| `branch` | 分支可以与操作系统的发行版本匹配，例如：v3.17。 |
| `repository` | 仓库可以用于[分组包](https://wiki.alpinelinux.org/wiki/Repositories) 或者只是 `main` 或类似的名称。 |
使用 HTTP 基本身份验证的示例请求：
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/file.apk \
https://gitea.example.com/api/packages/testuser/alpine/v3.17/main
```
如果您使用的是双重身份验证或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#authentication" >}})代替密码。
您不能将具有相同名称的文件两次发布到一个包中。您必须首先删除现有的包文件。
服务器将以以下的 HTTP 状态码响应：
| HTTP 状态码 | 含义 |
| ----------------- | ------------------------------------------ |
| `201 Created` | 软件包已发布。 |
| `400 Bad Request` | 软件包的名称、版本、分支、仓库或架构无效。 |
| `409 Conflict` | 具有相同参数组合的包文件已存在于软件包中。 |
## 删除软件包
要删除 Alpine 包，执行 HTTP 的 DELETE 操作。如果没有文件，这将同时删除包版本。
```
DELETE https://gitea.example.com/api/packages/{owner}/alpine/{branch}/{repository}/{architecture}/{filename}
```
| 参数 | 描述 |
| -------------- | -------------- |
| `owner` | 软件包的所有者 |
| `branch` | 要使用的分支名 |
| `repository` | 要使用的仓库名 |
| `architecture` | 软件包的架构 |
| `filename` | 要删除的文件名 |
使用 HTTP 基本身份验证的示例请求：
```shell
curl --user your_username:your_token_or_password -X DELETE \
https://gitea.example.com/api/packages/testuser/alpine/v3.17/main/test-package-1.0.0.apk
```
服务器将以以下的 HTTP 状态码响应：
| HTTP 状态码 | 含义 |
| ---------------- | ------------------ |
| `204 No Content` | 成功 |
| `404 Not Found` | 未找到软件包或文件 |
## 安装软件包
要从 Alpine 注册表安装软件包，请执行以下命令：
```shell
# use latest version
apk add {package_name}
# use specific version
apk add {package_name}={package_version}
```

4
docs/content/doc/usage/packages/cargo.en-us.md
View File

@ -1,6 +1,6 @@
---
date: "2022-11-20T00:00:00+00:00"
title: "Cargo Packages Repository"
title: "Cargo Package Registry"
slug: "cargo"
weight: 5
draft: false
@ -13,7 +13,7 @@ menu:
identifier: "cargo"
---
# Cargo Packages Repository
# Cargo Package Registry
Publish [Cargo](https://doc.rust-lang.org/stable/cargo/) packages for your user or organization.

110
docs/content/doc/usage/packages/cargo.zh-cn.md Normal file
View File

@ -0,0 +1,110 @@
---
date: "2022-11-20T00:00:00+00:00"
title: "Cargo 软件包注册表"
slug: "cargo"
weight: 5
draft: false
toc: false
menu:
sidebar:
parent: "packages"
name: "Cargo"
weight: 5
identifier: "cargo"
---
# Cargo 软件包注册表
为您的用户或组织发布 [Cargo](https://doc.rust-lang.org/stable/cargo/) 软件包。
**目录**
{{< toc >}}
## 要求
若要使用 Cargo 软件包注册表, 您需要安装 [Rust 和 Cargo](https://www.rust-lang.org/tools/install).
Cargo 将可用软件包的信息存储在一个存储在 git 仓库中的软件包索引中。
这个仓库是与注册表交互所必需的。
下面的部分将介绍如何创建它。
## 索引仓库
Cargo 将可用软件包的信息存储在一个存储在 git 仓库中的软件包索引中。
在 Gitea 中，这个仓库有一个特殊的名称叫做 `_cargo-index`。
在上传软件包之后，它的元数据会自动写入索引中。
不应手动修改这个注册表的内容。
用户或组织软件包设置页面允许创建这个索引仓库以及配置文件。
如果需要，此操作将重写配置文件。
例如，如果 Gitea 实例的域名已更改，这将非常有用。
如果存储在 Gitea 中的软件包与索引注册表中的信息不同步，设置页面允许重建这个索引注册表。
这个操作将遍历注册表中的所有软件包，并将它们的信息写入索引中。
如果有很多软件包，这个过程可能需要一些时间。
## 配置软件包注册表
要注册这个软件包注册表，必须更新 Cargo 的配置。
将以下文本添加到位于当前用户主目录中的配置文件中（例如 `~/.cargo/config.toml`）：
```
[registry]
default = "gitea"
[registries.gitea]
index = "https://gitea.example.com/{owner}/_cargo-index.git"
[net]
git-fetch-with-cli = true
```
| 参数 | 描述 |
| ------- | ---------------- |
| `owner` | 软件包的所有者。 |
如果这个注册表是私有的或者您想要发布新的软件包，您必须配置您的凭据。
将凭据部分添加到位于当前用户主目录中的凭据文件中（例如 `~/.cargo/credentials.toml`）：
```
[registries.gitea]
token = "Bearer {token}"
```
| 参数 | 描述 |
| ------- | ------------------------------------------------------------------------------------- |
| `token` | 您的[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}}) |
## 发布软件包
在项目中运行以下命令来发布软件包：
```shell
cargo publish
```
如果已经存在同名和版本的软件包，您将无法发布新的软件包。您必须先删除现有的软件包。
## 安装软件包
要从软件包注册表安装软件包，请执行以下命令：
```shell
cargo add {package_name}
```
| 参数 | 描述 |
| -------------- | ------------ |
| `package_name` | 软件包名称。 |
## 支持的命令
```
cargo publish
cargo add
cargo install
cargo yank
cargo unyank
cargo search
```

4
docs/content/doc/usage/packages/chef.en-us.md
View File

@ -1,6 +1,6 @@
---
date: "2023-01-20T00:00:00+00:00"
title: "Chef Packages Repository"
title: "Chef Package Registry"
slug: "chef"
weight: 5
draft: false
@ -13,7 +13,7 @@ menu:
identifier: "chef"
---
# Chef Packages Repository
# Chef Package Registry
Publish [Chef](https://chef.io/) cookbooks for your user or organization.

97
docs/content/doc/usage/packages/chef.zh-cn.md Normal file
View File

@ -0,0 +1,97 @@
---
date: "2023-01-20T00:00:00+00:00"
title: "Chef 软件包注册表"
slug: "chef"
weight: 5
draft: false
toc: false
menu:
sidebar:
parent: "packages"
name: "Chef"
weight: 5
identifier: "chef"
---
# Chef Package Registry
为您的用户或组织发布 [Chef](https://chef.io/) cookbooks。
**目录**
{{< toc >}}
## 要求
要使用 Chef 软件包注册表，您需要使用 [`knife`](https://docs.chef.io/workstation/knife/).
## 认证
Chef 软件包注册表不使用用户名和密码进行身份验证，而是使用私钥和公钥对请求进行签名。
请访问软件包所有者设置页面以创建必要的密钥对。
只有公钥存储在Gitea中。如果您丢失了私钥的访问权限，您必须重新生成密钥对。
[配置 `knife`](https://docs.chef.io/workstation/knife_setup/)，使用下载的私钥，并将 Gitea 用户名设置为 `client_name`。
## 配置软件包注册表
要将 [`knife` 配置](https://docs.chef.io/workstation/knife_setup/)为使用 Gitea 软件包注册表，请将 URL 添加到 `~/.chef/config.rb` 文件中。
```
knife[:supermarket_site] = 'https://gitea.example.com/api/packages/{owner}/chef'
```
| 参数 | 描述 |
| ------- | -------------- |
| `owner` | 软件包的所有者 |
## 发布软件包
若要发布 Chef 软件包，请执行以下命令：
```shell
knife supermarket share {package_name}
```
| 参数 | 描述 |
| -------------- | ---------- |
| `package_name` | 软件包名称 |
如果已经存在同名和版本的软件包，则无法发布新的软件包。您必须先删除现有的软件包。
## 安装软件包
要从软件包注册表中安装软件包，请执行以下命令：
```shell
knife supermarket install {package_name}
```
您可以指定软件包的版本，这是可选的：
```shell
knife supermarket install {package_name} {package_version}
```
| 参数 | 描述 |
| ----------------- | ---------- |
| `package_name` | 软件包名称 |
| `package_version` | 软件包版本 |
## 删除软件包
如果您想要从注册表中删除软件包，请执行以下命令：
```shell
knife supermarket unshare {package_name}
```
可选地，您可以指定软件包的版本：
```shell
knife supermarket unshare {package_name}/versions/{package_version}
```
| 参数 | 描述 |
| ----------------- | ---------- |
| `package_name` | 软件包名称 |
| `package_version` | 软件包版本 |

4
docs/content/doc/usage/packages/composer.en-us.md
View File

@ -1,6 +1,6 @@
---
date: "2021-07-20T00:00:00+00:00"
title: "Composer Packages Repository"
title: "Composer Package Registry"
slug: "composer"
weight: 10
draft: false
@ -13,7 +13,7 @@ menu:
identifier: "composer"
---
# Composer Packages Repository
# Composer Package Registry
Publish [Composer](https://getcomposer.org/) packages for your user or organization.

123
docs/content/doc/usage/packages/composer.zh-cn.md Normal file
View File

@ -0,0 +1,123 @@
---
date: "2021-07-20T00:00:00+00:00"
title: "Composer 软件包注册表"
slug: "composer"
weight: 10
draft: false
toc: false
menu:
sidebar:
parent: "packages"
name: "Composer"
weight: 10
identifier: "composer"
---
# Composer 软件包注册表
为您的用户或组织发布 [Composer](https://getcomposer.org/) 软件包。
**目录**
{{< toc >}}
## 要求
要使用 Composer 软件包注册表，您可以使用 [Composer](https://getcomposer.org/download/) 消费，并使用类似 `curl` 的 HTTP 上传客户端发布软件包。
## 发布软件包
要发布 Composer 软件包，请执行 HTTP `PUT` 操作，将软件包内容放入请求体中。
软件包内容必须是包含 `composer.json` 文件的压缩 PHP 项目。
如果已经存在同名和版本的软件包，则无法发布新的软件包。您必须先删除现有的软件包。
```
PUT https://gitea.example.com/api/packages/{owner}/composer
```
| 参数 | 描述 |
| ------- | -------------- |
| `owner` | 软件包的所有者 |
如果 `composer.json` 文件不包含 `version` 属性，您必须将其作为查询参数提供：
```
PUT https://gitea.example.com/api/packages/{owner}/composer?version={x.y.z}
```
使用 HTTP 基本身份验证的示例请求：
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/project.zip \
https://gitea.example.com/api/packages/testuser/composer
```
或者将软件包版本指定为查询参数：
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/project.zip \
https://gitea.example.com/api/packages/testuser/composer?version=1.0.3
```
如果您使用 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码。
服务器将以以下 HTTP 状态码响应。
| HTTP 状态码 | 含义 |
| ----------------- | ----------------------------------------------------------- |
| `201 Created` | 软件包已发布 |
| `400 Bad Request` | 软件包名称和/或版本无效，或具有相同名称和版本的软件包已存在 |
## 配置软件包注册表
要注册软件包注册表，您需要将其添加到 Composer 的 `config.json` 文件中（通常可以在 `<user-home-dir>/.composer/config.json` 中找到）：
```json
{
"repositories": [{
"type": "composer",
"url": "https://gitea.example.com/api/packages/{owner}/composer"
}
]
}
```
要使用凭据访问软件包注册表，您必须在 `auth.json` 文件中指定它们，如下所示：
```json
{
"http-basic": {
"gitea.example.com": {
"username": "{username}",
"password": "{password}"
}
}
}
```
| 参数 | 描述 |
| ---------- | --------------------------- |
| `owner` | 软件包的所有者 |
| `username` | 您的 Gitea 用户名 |
| `password` | 您的Gitea密码或个人访问令牌 |
## 安装软件包
要从软件包注册表中安装软件包，请执行以下命令：
```shell
composer require {package_name}
```
您可以指定软件包的版本，这是可选的：
```shell
composer require {package_name}:{package_version}
```
| 参数 | 描述 |
| ----------------- | ---------- |
| `package_name` | 软件包名称 |
| `package_version` | 软件包版本 |

4
docs/content/doc/usage/packages/conan.en-us.md
View File

@ -1,6 +1,6 @@
---
date: "2021-07-20T00:00:00+00:00"
title: "Conan Packages Repository"
title: "Conan Package Registry"
slug: "conan"
weight: 20
draft: false
@ -13,7 +13,7 @@ menu:
identifier: "conan"
---
# Conan Packages Repository
# Conan Package Registry
Publish [Conan](https://conan.io/) packages for your user or organization.

102
docs/content/doc/usage/packages/conan.zh-cn.md Normal file
View File

@ -0,0 +1,102 @@
---
date: "2021-07-20T00:00:00+00:00"
title: "Conan 软件包注册表"
slug: "conan"
weight: 20
draft: false
toc: false
menu:
sidebar:
parent: "packages"
name: "Conan"
weight: 20
identifier: "conan"
---
# Conan 软件包注册表
为您的用户或组织发布 [Conan](https://conan.io/) 软件包。
**目录**
{{< toc >}}
## 要求
要使用 [conan](https://conan.io/downloads.html) 软件包注册表，您需要使用 conan 命令行工具来消费和发布软件包。
## 配置软件包注册表
要注册软件包注册表，您需要配置一个新的 Conan remote：
```shell
conan remote add {remote} https://gitea.example.com/api/packages/{owner}/conan
conan user --remote {remote} --password {password} {username}
```
| 参数 | 描述 |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `remote` | 远程名称。 |
| `username` | 您的 Gitea 用户名。 |
| `password` | 您的 Gitea 密码。如果您使用 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码。 |
| `owner` | 软件包的所有者。 |
例如:
```shell
conan remote add gitea https://gitea.example.com/api/packages/testuser/conan
conan user --remote gitea --password password123 testuser
```
## 发布软件包
通过运行以下命令发布 Conan 软件包：
```shell
conan upload --remote={remote} {recipe}
```
| 参数 | 描述 |
| -------- | --------------- |
| `remote` | 远程名称 |
| `recipe` | 要上传的 recipe |
For example:
```shell
conan upload --remote=gitea ConanPackage/1.2@gitea/final
```
Gitea Conan 软件包注册表支持完整的[版本修订](https://docs.conan.io/en/latest/versioning/revisions.html)。
## 安装软件包
要从软件包注册表中安装Conan软件包，请执行以下命令：
```shell
conan install --remote={remote} {recipe}
```
| 参数 | 描述 |
| -------- | --------------- |
| `remote` | 远程名称 |
| `recipe` | 要下载的 recipe |
例如：
```shell
conan install --remote=gitea ConanPackage/1.2@gitea/final
```
## 支持的命令
```
conan install
conan get
conan info
conan search
conan upload
conan user
conan download
conan remove
```

4
docs/content/doc/usage/packages/conda.en-us.md
View File

@ -1,6 +1,6 @@
---
date: "2022-12-28T00:00:00+00:00"
title: "Conda Packages Repository"
title: "Conda Package Registry"
slug: "conda"
weight: 25
draft: false
@ -13,7 +13,7 @@ menu:
identifier: "conda"
---
# Conda Packages Repository
# Conda Package Registry
Publish [Conda](https://docs.conda.io/en/latest/) packages for your user or organization.

86
docs/content/doc/usage/packages/conda.zh-cn.md Normal file
View File

@ -0,0 +1,86 @@
---
date: "2022-12-28T00:00:00+00:00"
title: "Conda 软件包注册表"
slug: "conda"
weight: 25
draft: false
toc: false
menu:
sidebar:
parent: "packages"
name: "Conda"
weight: 25
identifier: "conda"
---
# Conda 软件包注册表
为您的用户或组织发布 [Conda](https://docs.conda.io/en/latest/) 软件包。
**目录**
{{< toc >}}
## 要求
要使用 Conda 软件包注册表，您需要使用 [conda](https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html) 命令行工具。
## 配置软件包注册表
要注册软件包注册表并提供凭据，请编辑您的 `.condarc` 文件：
```yaml
channel_alias: https://gitea.example.com/api/packages/{owner}/conda
channels:
- https://gitea.example.com/api/packages/{owner}/conda
default_channels:
- https://gitea.example.com/api/packages/{owner}/conda
```
| 占位符 | 描述 |
| ------- | -------------- |
| `owner` | 软件包的所有者 |
有关各个设置的解释，请参阅[官方文档](https://conda.io/projects/conda/en/latest/user-guide/configuration/use-condarc.html)。
如果需要提供凭据，可以将它们作为通道 URL 的一部分嵌入（`https://user:password@gitea.example.com/...`）。
## 发布软件包
要发布一个软件包，请执行一个HTTP `PUT`操作，请求正文中包含软件包内容。
```
PUT https://gitea.example.com/api/packages/{owner}/conda/{channel}/{filename}
```
| 占位符 | 描述 |
| ---------- | --------------------------------------------------------------------------------------------------- |
| `owner` | 软件包的所有者 |
| `channel` | 软件包的[通道](https://conda.io/projects/conda/en/latest/user-guide/concepts/channels.html)（可选） |
| `filename` | 文件名 |
使用HTTP基本身份验证的示例请求：
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/package-1.0.conda \
https://gitea.example.com/api/packages/testuser/conda/package-1.0.conda
```
如果已经存在同名和版本的软件包，则无法发布软件包。您必须先删除现有的软件包。
## 安装软件包
要从软件包注册表中安装软件包，请执行以下命令之一：
```shell
conda install {package_name}
conda install {package_name}={package_version}
conda install -c {channel} {package_name}
```
| 参数 | 描述 |
| ----------------- | -------------------- |
| `package_name` | 软件包的名称 |
| `package_version` | 软件包的版本 |
| `channel` | 软件包的通道（可选） |

94
docs/content/doc/usage/packages/container.zh-cn.md Normal file
View File

@ -0,0 +1,94 @@
---
date: "2021-07-20T00:00:00+00:00"
title: "容器注册表"
slug: "container"
weight: 30
draft: false
toc: false
menu:
sidebar:
parent: "packages"
name: "容器"
weight: 30
identifier: "container"
---
# 容器注册表
为您的用户或组织发布符合 [Open Container Initiative(OCI)](https://opencontainers.org/) 规范的镜像。
该容器注册表遵循 OCI 规范，并支持所有兼容的镜像类型，如 [Docker](https://www.docker.com/) 和 [Helm Charts](https://helm.sh/)。
**目录**
{{< toc >}}
## 目录
要使用容器注册表，您可以使用适用于特定镜像类型的工具。
以下示例使用 `docker` 客户端。
## 登录容器注册表
要推送镜像或者如果镜像位于私有注册表中，您需要进行身份验证：
```shell
docker login gitea.example.com
```
如果您使用的是 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码进行身份验证。
## 镜像命名约定
镜像必须遵循以下命名约定：
`{registry}/{owner}/{image}`
例如，以下是所有者为 `testuser` 的有效镜像名称示例：
`gitea.example.com/testuser/myimage`
`gitea.example.com/testuser/my-image`
`gitea.example.com/testuser/my/image`
**注意:** 该注册表仅支持大小写不敏感的标签名称。因此，`image:tag` 和 `image:Tag` 将被视为相同的镜像和标签。
## 推送镜像
通过执行以下命令来推送镜像：
```shell
docker push gitea.example.com/{owner}/{image}:{tag}
```
| 参数 | 描述 |
| ------- | ------------ |
| `owner` | 镜像的所有者 |
| `image` | 镜像的名称 |
| `tag` | 镜像的标签 |
例如：
```shell
docker push gitea.example.com/testuser/myimage:latest
```
## 拉取镜像
通过执行以下命令来拉取镜像：
```shell
docker pull gitea.example.com/{owner}/{image}:{tag}
```
| Parameter | Description |
| --------- | ------------ |
| `owner` | 镜像的所有者 |
| `image` | 镜像的名称 |
| `tag` | 镜像的标签 |
例如：
```shell
docker pull gitea.example.com/testuser/myimage:latest
```

4
docs/content/doc/usage/packages/cran.en-us.md
View File

@ -1,6 +1,6 @@
---
date: "2023-01-01T00:00:00+00:00"
title: "CRAN Packages Repository"
title: "CRAN Package Registry"
slug: "cran"
draft: false
toc: false
@ -12,7 +12,7 @@ menu:
identifier: "cran"
---
# CRAN Packages Repository
# CRAN Package Registry
Publish [R](https://www.r-project.org/) packages to a [CRAN](https://cran.r-project.org/)-like registry for your user or organization.

6
docs/content/doc/usage/packages/debian.en-us.md
View File

@ -1,7 +1,7 @@
---
date: "2023-01-07T00:00:00+00:00"
title: "Debian Packages Repository"
slug: "packages/debian"
title: "Debian Package Registry"
slug: "debian"
draft: false
toc: false
menu:
@ -12,7 +12,7 @@ menu:
identifier: "debian"
---
# Debian Packages Repository
# Debian Package Registry
Publish [Debian](https://www.debian.org/distrib/packages) packages for your user or organization.

134
docs/content/doc/usage/packages/debian.zh-cn.md Normal file
View File

@ -0,0 +1,134 @@
---
date: "2023-01-07T00:00:00+00:00"
title: "Debian 软件包注册表"
slug: "debian"
draft: false
toc: false
menu:
sidebar:
parent: "packages"
name: "Debian"
weight: 35
identifier: "debian"
---
# Debian 软件包注册表
为您的用户或组织发布 [Debian](https://www.debian.org/distrib/packages) 软件包。
**目录**
{{< toc >}}
## 要求
要使用 Debian 注册表，您需要使用类似于 `curl` 的 HTTP 客户端进行上传，并使用类似于 `apt` 的软件包管理器消费软件包。
以下示例使用 `apt`。
## 配置软件包注册表
要注册 Debian 注册表，请将 URL 添加到已知 `apt` 源列表中：
```shell
echo "deb https://gitea.example.com/api/packages/{owner}/debian {distribution} {component}" | sudo tee -a /etc/apt/sources.list.d/gitea.list
```
| 占位符 | 描述 |
| -------------- | -------------- |
| `owner` | 软件包的所有者 |
| `distribution` | 要使用的发行版 |
| `component` | 要使用的组件 |
如果注册表是私有的，请在 URL 中提供凭据。您可以使用密码或[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})：
```shell
echo "deb https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/debian {distribution} {component}" | sudo tee -a /etc/apt/sources.list.d/gitea.list
```
Debian 注册表文件使用 PGP 密钥进行签名，`apt` 必须知道该密钥：
```shell
sudo curl https://gitea.example.com/api/packages/{owner}/debian/repository.key -o /etc/apt/trusted.gpg.d/gitea-{owner}.asc
```
然后更新本地软件包索引：
```shell
apt update
```
## 发布软件包
要发布一个 Debian 软件包（`*.deb`），执行 HTTP `PUT` 操作，并将软件包内容放入请求主体中。
```
PUT https://gitea.example.com/api/packages/{owner}/debian/pool/{distribution}/{component}/upload
```
| 参数 | 描述 |
| -------------- | ----------------------------------------------------- |
| `owner` | 软件包的所有者 |
| `distribution` | 发行版，可能与操作系统的发行版名称匹配，例如 `bionic` |
| `component` | 组件，可用于分组软件包，或仅为 `main` 或类似的组件。 |
使用 HTTP 基本身份验证的示例请求：
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/file.deb \
https://gitea.example.com/api/packages/testuser/debian/pool/bionic/main/upload
```
如果您使用 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码。
您无法向软件包中多次发布具有相同名称的文件。您必须首先删除现有的软件包版本。
服务器将使用以下 HTTP 状态代码进行响应。
| HTTP 状态码 | 意义 |
| ----------------- | ---------------------------------------- |
| `201 Created` | 软件包已发布 |
| `400 Bad Request` | 软件包名称、版本、发行版、组件或架构无效 |
| `409 Conflict` | 具有相同参数组合的软件包文件已经存在 |
## 删除软件包
要删除 Debian 软件包，请执行 HTTP `DELETE` 操作。如果没有文件留下，这将同时删除软件包版本。
```
DELETE https://gitea.example.com/api/packages/{owner}/debian/pool/{distribution}/{component}/{package_name}/{package_version}/{architecture}
```
| 参数 | 描述 |
| ----------------- | -------------- |
| `owner` | 软件包的所有者 |
| `package_name` | 软件包名称 |
| `package_version` | 软件包版本 |
| `distribution` | 软件包发行版 |
| `component` | 软件包组件 |
| `architecture` | 软件包架构 |
使用 HTTP 基本身份验证的示例请求：
```shell
curl --user your_username:your_token_or_password -X DELETE \
https://gitea.example.com/api/packages/testuser/debian/pools/bionic/main/test-package/1.0.0/amd64
```
服务器将使用以下 HTTP 状态代码进行响应。
| HTTP 状态码 | 含义 |
| ---------------- | ------------------ |
| `204 No Content` | 成功 |
| `404 Not Found` | 找不到软件包或文件 |
## 安装软件包
要从 Debian 注册表安装软件包，请执行以下命令:
```shell
# use latest version
apt install {package_name}
# use specific version
apt install {package_name}={package_version}
```

4
docs/content/doc/usage/packages/generic.en-us.md
View File

@ -1,6 +1,6 @@
---
date: "2021-07-20T00:00:00+00:00"
title: "Generic Packages Repository"
title: "Generic Package Registry"
slug: "generic"
weight: 40
draft: false
@ -13,7 +13,7 @@ menu:
identifier: "generic"
---
# Generic Packages Repository
# Generic Package Registry
Publish generic files, like release binaries or other output, for your user or organization.

148
docs/content/doc/usage/packages/generic.zh-cn.md Normal file
View File

@ -0,0 +1,148 @@
---
date: "2021-07-20T00:00:00+00:00"
title: "通用软件包注册表"
slug: "generic"
weight: 40
draft: false
toc: false
menu:
sidebar:
parent: "packages"
name: "通用"
weight: 40
identifier: "generic"
---
# 通用软件包注册表
发布通用文件，如发布二进制文件或其他输出，供您的用户或组织使用。
**目录**
{{< toc >}}
## 身份验证软件包注册表
要身份验证软件包注册表，您需要提供[自定义 HTTP 头或使用 HTTP 基本身份验证]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})。
## 发布软件包
要发布通用软件包，请执行 HTTP `PUT` 操作，并将软件包内容放入请求主体中。
您无法向软件包中多次发布具有相同名称的文件。您必须首先删除现有的软件包版本。
```
PUT https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name}
```
| 参数 | 描述 |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `owner` | 软件包的所有者。 |
| `package_name` | 软件包名称。它只能包含小写字母 (`a-z`)、大写字母 (`A-Z`)、数字 (`0-9`)、点号 (`.`)、连字符 (`-`)、加号 (`+`) 或下划线 (`_`) |
| `package_version` | 软件包版本，一个非空字符串，不包含前导或尾随空格 |
| `file_name` | 文件名。它只能包含小写字母 (`a-z`)、大写字母 (`A-Z`)、数字 (`0-9`)、点号 (`.`)、连字符 (`-`)、加号 (`+`) 或下划线 (`_`) |
使用 HTTP 基本身份验证的示例请求：
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/file.bin \
https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin
```
如果您使用 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码。
服务器将使用以下 HTTP 状态代码进行响应。
| HTTP 状态码 | 意义 |
| ----------------- | ---------------------------------- |
| `201 Created` | 软件包已发布 |
| `400 Bad Request` | 软件包名称和/或版本和/或文件名无效 |
| `409 Conflict` | 具有相同名称的文件已存在于软件包中 |
## 下载软件包
要下载通用软件包，请执行 HTTP `GET` 操作。
```
GET https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name}
```
| 参数 | 描述 |
| ----------------- | -------------- |
| `owner` | 软件包的所有者 |
| `package_name` | 软件包名称 |
| `package_version` | 软件包版本 |
| `file_name` | 文件名 |
文件内容将在响应主体中返回。响应的内容类型为 `application/octet-stream`。
服务器将使用以下 HTTP 状态代码进行响应。
```shell
curl --user your_username:your_token_or_password \
https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin
```
服务器会以以下 HTTP 状态码进行响应：
| HTTP 状态码 | 含义 |
| --------------- | -------------------- |
| `200 OK` | 成功 |
| `404 Not Found` | 找不到软件包或者文件 |
## 删除软件包
要删除通用软件包，请执行 HTTP DELETE 操作。这将同时删除该版本的所有文件。
```
DELETE https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}
```
| 参数 | 描述 |
| ----------------- | -------------- |
| `owner` | 软件包的所有者 |
| `package_name` | 软件包名称 |
| `package_version` | 软件包版本 |
服务器将使用以下 HTTP 状态代码进行响应。
```shell
curl --user your_username:your_token_or_password -X DELETE \
https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0
```
The server responds with the following HTTP Status codes.
| HTTP 状态码 | 意义 |
| ---------------- | ------------ |
| `204 No Content` | 成功 |
| `404 Not Found` | 找不到软件包 |
## 删除软件包文件
要删除通用软件包的文件，请执行 HTTP `DELETE` 操作。如果没有文件留下，这将同时删除软件包版本。
```
DELETE https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{filename}
```
| 参数 | 描述 |
| ----------------- | -------------- |
| `owner` | 软件包的所有者 |
| `package_name` | 软件包名称 |
| `package_version` | 软件包版本 |
| `filename` | 文件名 |
使用 HTTP 基本身份验证的示例请求：
```shell
curl --user your_username:your_token_or_password -X DELETE \
https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin
```
服务器将使用以下 HTTP 状态代码进行响应：
| HTTP 状态码 | 含义 |
| ---------------- | ------------------ |
| `204 No Content` | 成功 |
| `404 Not Found` | 找不到软件包或文件 |

4
docs/content/doc/usage/packages/go.en-us.md
View File

@ -1,6 +1,6 @@
---
date: "2023-05-10T00:00:00+00:00"
title: "Go Packages Repository"
title: "Go Package Registry"
slug: "go"
weight: 45
draft: false
@ -13,7 +13,7 @@ menu:
identifier: "go"
---
# Go Packages Repository
# Go Package Registry
Publish Go packages for your user or organization.

77
docs/content/doc/usage/packages/go.zh-cn.md Normal file
View File

@ -0,0 +1,77 @@
---
date: "2023-05-10T00:00:00+00:00"
title: "Go 软件包注册表"
slug: "go"
weight: 45
draft: false
toc: false
menu:
sidebar:
parent: "packages"
name: "Go"
weight: 45
identifier: "go"
---
# Go 软件包注册表
为您的用户或组织发布 Go 软件包。
**目录**
{{< toc >}}
## 发布软件包
要发布 Go 软件包，请执行 HTTP `PUT` 操作，并将软件包内容放入请求主体中。
如果已经存在相同名称和版本的软件包，您无法发布软件包。您必须首先删除现有的软件包。
该软件包必须遵循[文档中的结构](https://go.dev/ref/mod#zip-files)。
```
PUT https://gitea.example.com/api/packages/{owner}/go/upload
```
| 参数 | 描述 |
| ------- | -------------- |
| `owner` | 软件包的所有者 |
要身份验证到软件包注册表，您需要提供[自定义 HTTP 头或使用 HTTP 基本身份验证]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})：
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/file.zip \
https://gitea.example.com/api/packages/testuser/go/upload
```
如果您使用的是 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码进行身份验证。
服务器将使用以下 HTTP 状态代码进行响应。
| HTTP 状态码 | 含义 |
| ----------------- | -------------------------- |
| `201 Created` | 软件包已发布 |
| `400 Bad Request` | 软件包无效 |
| `409 Conflict` | 具有相同名称的软件包已存在 |
## 安装软件包
要安装Go软件包，请指示Go使用软件包注册表作为代理：
```shell
# 使用最新版本
GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name}
# 或者
GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name}@latest
# 使用特定版本
GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name}@{package_version}
```
| 参数 | 描述 |
| ----------------- | -------------- |
| `owner` | 软件包的所有者 |
| `package_name` | 软件包名称 |
| `package_version` | 软件包版本 |
如果软件包的所有者是私有的，则需要[提供凭据](https://go.dev/ref/mod#private-module-proxy-auth)。
有关 `GOPROXY` 环境变量的更多信息以及如何防止数据泄漏的信息，请[参阅文档](https://go.dev/ref/mod#private-modules)。

68
docs/content/doc/usage/packages/helm.zh-cn.md Normal file
View File

@ -0,0 +1,68 @@
---
date: "2022-04-14T00:00:00+00:00"
title: "Helm Chart 注册表"
slug: "helm"
weight: 50
draft: false
toc: false
menu:
sidebar:
parent: "packages"
name: "Helm"
weight: 50
identifier: "helm"
---
# Helm Chart 注册表
为您的用户或组织发布 [Helm](https://helm.sh/) charts。
**目录**
{{< toc >}}
## 要求
要使用 Helm Chart 注册表，可以使用诸如 `curl` 或 [`helm cm-push`](https://github.com/chartmuseum/helm-push/) 插件之类的简单HTTP客户端。
## 发布软件包
通过运行以下命令来发布软件包：
```shell
curl --user {username}:{password} -X POST --upload-file ./{chart_file}.tgz https://gitea.example.com/api/packages/{owner}/helm/api/charts
```
或者使用 `helm cm-push` 插件：
```shell
helm repo add --username {username} --password {password} {repo} https://gitea.example.com/api/packages/{owner}/helm
helm cm-push ./{chart_file}.tgz {repo}
```
| 参数 | 描述 |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `username` | 您的Gitea用户名 |
| `password` | 您的Gitea密码。如果您使用的是2FA或OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码进行身份验证。 |
| `repo` | 仓库名称 |
| `chart_file` | Helm Chart 归档文件 |
| `owner` | 软件包的所有者 |
## 安装软件包
要从注册表中安装Helm Chart，请执行以下命令：
```shell
helm repo add --username {username} --password {password} {repo} https://gitea.example.com/api/packages/{owner}/helm
helm repo update
helm install {name} {repo}/{chart}
```
| 参数 | 描述 |
| ---------- | --------------------------- |
| `username` | 您的Gitea用户名 |
| `password` | 您的Gitea密码或个人访问令牌 |
| `repo` | 存储库的名称 |
| `owner` | 软件包的所有者 |
| `name` | 本地名称 |
| `chart` | Helm Chart的名称 |

4
docs/content/doc/usage/packages/maven.en-us.md
View File

@ -1,6 +1,6 @@
---
date: "2021-07-20T00:00:00+00:00"
title: "Maven Packages Repository"
title: "Maven Package Registry"
slug: "maven"
weight: 60
draft: false
@ -13,7 +13,7 @@ menu:
identifier: "maven"
---
# Maven Packages Repository
# Maven Package Registry
Publish [Maven](https://maven.apache.org) packages for your user or organization.

167
docs/content/doc/usage/packages/maven.zh-cn.md Normal file
View File

@ -0,0 +1,167 @@
---
date: "2021-07-20T00:00:00+00:00"
title: "Maven 软件包注册表"
slug: "maven"
weight: 60
draft: false
toc: false
menu:
sidebar:
parent: "packages"
name: "Maven"
weight: 60
identifier: "maven"
---
# Maven 软件包注册表
为您的用户或组织发布 [Maven](https://maven.apache.org) 软件包。
**目录**
{{< toc >}}
## 要求
要使用 Maven 软件包注册表，您可以使用 [Maven](https://maven.apache.org/install.html) 或 [Gradle](https://gradle.org/install/)。
以下示例使用 `Maven` 和 `Gradle Groovy`。
## 配置软件包注册表
要注册软件包注册表，首先需要将访问令牌添加到 [`settings.xml`](https://maven.apache.org/settings.html) 文件中：
```xml
<settings>
<servers>
<server>
<id>gitea</id>
<configuration>
<httpHeaders>
<property>
<name>Authorization</name>
<value>token {access_token}</value>
</property>
</httpHeaders>
</configuration>
</server>
</servers>
</settings>
```
然后在项目的 `pom.xml` 文件中添加以下部分：
```xml
<repositories>
<repository>
<id>gitea</id>
<url>https://gitea.example.com/api/packages/{owner}/maven</url>
</repository>
</repositories>
<distributionManagement>
<repository>
<id>gitea</id>
<url>https://gitea.example.com/api/packages/{owner}/maven</url>
</repository>
<snapshotRepository>
<id>gitea</id>
<url>https://gitea.example.com/api/packages/{owner}/maven</url>
</snapshotRepository>
</distributionManagement>
```
| 参数 | 描述 |
| -------------- | ------------------------------------------------------------------------------------- |
| `access_token` | 您的[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}}) |
| `owner` | 软件包的所有者 |
### Gradle variant
如果您计划在项目中添加来自 Gitea 实例的一些软件包，请将其添加到 repositories 部分中：
```groovy
repositories {
// other repositories
maven { url "https://gitea.example.com/api/packages/{owner}/maven" }
}
```
在 Groovy gradle 中，您可以在发布部分中包含以下脚本：
```groovy
publishing {
// 其他发布设置
repositories {
maven {
name = "Gitea"
url = uri("https://gitea.example.com/api/packages/{owner}/maven")
credentials(HttpHeaderCredentials) {
name = "Authorization"
value = "token {access_token}"
}
authentication {
header(HttpHeaderAuthentication)
}
}
}
}
```
## 发布软件包
要发布软件包，只需运行以下命令：
```shell
mvn deploy
```
或者，如果您使用的是 Gradle，请使用 `gradle` 命令和 `publishAllPublicationsToGiteaRepository` 任务：
```groovy
./gradlew publishAllPublicationsToGiteaRepository
```
如果您想要将预构建的软件包发布到注册表中，可以使用 [`mvn deploy:deploy-file`](https://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html) 命令：
```shell
mvn deploy:deploy-file -Durl=https://gitea.example.com/api/packages/{owner}/maven -DrepositoryId=gitea -Dfile=/path/to/package.jar
```
| 参数 | 描述 |
| ------- | -------------- |
| `owner` | 软件包的所有者 |
如果存在相同名称和版本的软件包，您无法发布该软件包。您必须先删除现有的软件包。
## 安装软件包
要从软件包注册表中安装 Maven 软件包，请在项目的 `pom.xml` 文件中添加新的依赖项：
```xml
<dependency>
<groupId>com.test.package</groupId>
<artifactId>test_project</artifactId>
<version>1.0.0</version>
</dependency>
```
在 `Gradle Groovy` 中类似的操作如下：
```groovy
implementation "com.test.package:test_project:1.0.0"
```
然后运行：
```shell
mvn install
```
## 支持的命令
```
mvn install
mvn deploy
mvn dependency:get:
```

4
docs/content/doc/usage/packages/npm.en-us.md
View File

@ -1,6 +1,6 @@
---
date: "2021-07-20T00:00:00+00:00"
title: "npm Packages Repository"
title: "npm Package Registry"
slug: "npm"
weight: 70
draft: false
@ -13,7 +13,7 @@ menu:
identifier: "npm"
---
# npm Packages Repository
# npm Package Registry
Publish [npm](https://www.npmjs.com/) packages for your user or organization.

145
docs/content/doc/usage/packages/npm.zh-cn.md Normal file
View File

@ -0,0 +1,145 @@
---
date: "2021-07-20T00:00:00+00:00"
title: "npm 软件包注册表"
slug: "npm"
weight: 70
draft: false
toc: false
menu:
sidebar:
parent: "packages"
name: "npm"
weight: 70
identifier: "npm"
---
# npm Package Registry
为您的用户或组织发布 [npm](https://www.npmjs.com/) 包。
**目录**
{{< toc >}}
## 要求
要使用 npm 包注册表，您需要安装 [Node.js](https://nodejs.org/en/download/) 以及与之配套的软件包管理器，例如 [Yarn](https://classic.yarnpkg.com/en/docs/install) 或 [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/) 本身。
该注册表支持[作用域](https://docs.npmjs.com/misc/scope/)和非作用域软件包。
以下示例使用具有作用域 `@test` 的 `npm` 工具。
## 配置软件包注册表
要注册软件包注册表，您需要配置一个新的软件包源。
```shell
npm config set {scope}:registry https://gitea.example.com/api/packages/{owner}/npm/
npm config set -- '//gitea.example.com/api/packages/{owner}/npm/:_authToken' "{token}"
```
| 参数 | 描述 |
| ------- | --------------------------------------------------------------------------------------- |
| `scope` | 软件包的作用域 |
| `owner` | 软件包的所有者 |
| `token` | 您的[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})。 |
例如：
```shell
npm config set @test:registry https://gitea.example.com/api/packages/testuser/npm/
npm config set -- '//gitea.example.com/api/packages/testuser/npm/:_authToken' "personal_access_token"
```
或者，不使用作用域：
```shell
npm config set registry https://gitea.example.com/api/packages/testuser/npm/
npm config set -- '//gitea.example.com/api/packages/testuser/npm/:_authToken' "personal_access_token"
```
## 发布软件包
在项目中运行以下命令发布软件包：
```shell
npm publish
```
如果已经存在相同名称和版本的软件包，您无法发布该软件包。您必须先删除现有的软件包。
## 删除软件包
通过运行以下命令删除软件包：
```shell
npm unpublish {package_name}[@{package_version}]
```
| 参数 | 描述 |
| ----------------- | ---------- |
| `package_name` | 软件包名称 |
| `package_version` | 软件包版本 |
例如
```shell
npm unpublish @test/test_package
npm unpublish @test/test_package@1.0.0
```
## 安装软件包
要从软件包注册表中安装软件包，请执行以下命令：
```shell
npm install {package_name}
```
| 参数 | 描述 |
| -------------- | ---------- |
| `package_name` | 软件包名称 |
例如：
```shell
npm install @test/test_package
```
## 给软件包打标签
该注册表支持[版本标签](https://docs.npmjs.com/adding-dist-tags-to-packages/)，可以通过 `npm dist-tag` 管理：
```shell
npm dist-tag add {package_name}@{version} {tag}
```
| 参数 | 描述 |
| -------------- | ---------- |
| `package_name` | 软件包名称 |
| `version` | 软件包版本 |
| `tag` | 软件包标签 |
例如：
```shell
npm dist-tag add test_package@1.0.2 release
```
标签名称不能是有效的版本。所有可解析为版本的标签名称都将被拒绝。
## 搜索软件包
该注册表支持[搜索](https://docs.npmjs.com/cli/v7/commands/npm-search/)，但不支持像 `author:gitea` 这样的特殊搜索限定符。
## 支持的命令
```
npm install
npm ci
npm publish
npm unpublish
npm dist-tag
npm view
npm search
```

4
docs/content/doc/usage/packages/nuget.en-us.md
View File

@ -1,6 +1,6 @@
---
date: "2021-07-20T00:00:00+00:00"
title: "NuGet Packages Repository"
title: "NuGet Package Registry"
slug: "nuget"
weight: 80
draft: false
@ -13,7 +13,7 @@ menu:
identifier: "nuget"
---
# NuGet Packages Repository
# NuGet Package Registry
Publish [NuGet](https://www.nuget.org/) packages for your user or organization. The package registry supports the V2 and V3 API protocol and you can work with [NuGet Symbol Packages](https://docs.microsoft.com/en-us/nuget/create-packages/symbol-packages-snupkg) too.

118
docs/content/doc/usage/packages/nuget.zh-cn.md Normal file
View File

@ -0,0 +1,118 @@
---
date: "2021-07-20T00:00:00+00:00"
title: "NuGet 软件包注册表"
slug: "nuget"
weight: 80
draft: false
toc: false
menu:
sidebar:
parent: "packages"
name: "NuGet"
weight: 80
identifier: "nuget"
---
# NuGet 软件包注册表
发布适用于您的用户或组织的 [NuGet](https://www.nuget.org/) 软件包。软件包注册表支持 V2 和 V3 API 协议，并且您还可以使用 [NuGet 符号软件包](https://docs.microsoft.com/en-us/nuget/create-packages/symbol-packages-snupkg)。
**目录**
{{< toc >}}
## 要求
要使用 NuGet 软件包注册表，您可以使用命令行界面工具，以及各种集成开发环境（IDE）中的 NuGet 功能，如 Visual Studio。有关 NuGet 客户端的更多信息，请参[阅官方文档](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools)。
以下示例使用 `dotnet nuget` 工具。
## 配置软件包注册表
要注册软件包注册表，您需要配置一个新的NuGet源：
```shell
dotnet nuget add source --name {source_name} --username {username} --password {password} https://gitea.example.com/api/packages/{owner}/nuget/index.json
```
| 参数 | 描述 |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `source_name` | 所需源名称 |
| `username` | 您的Gitea用户名 |
| `password` | 您的Gitea密码。如果您使用2FA或OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})代替密码。 |
| `owner` | 软件包的所有者 |
例如：
```shell
dotnet nuget add source --name gitea --username testuser --password password123 https://gitea.example.com/api/packages/testuser/nuget/index.json
```
您可以在不提供凭据的情况下添加源，并在发布软件包时使用--api-key参数。在这种情况下，您需要提供[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})。
## 发布软件包
通过运行以下命令发布软件包：
```shell
dotnet nuget push --source {source_name} {package_file}
```
| 参数 | 描述 |
| -------------- | ---------------------------- |
| `source_name` | 所需源名称 |
| `package_file` | 软件包 `.nupkg` 文件的路径。 |
例如：
```shell
dotnet nuget push --source gitea test_package.1.0.0.nupkg
```
如果已经存在相同名称和版本的软件包，您无法发布该软件包。您必须先删除现有的软件包。
### 符号软件包
NuGet 软件包注册表支持构建用于符号服务器的符号软件包。客户端可以请求嵌入在符号软件包（`.snupkg`）中的 PDB 文件。
为此，请将 NuGet 软件包注册表注册为符号源：
```
https://gitea.example.com/api/packages/{owner}/nuget/symbols
```
| 参数 | 描述 |
| ------- | -------------------- |
| `owner` | 软件包注册表的所有者 |
例如：
```
https://gitea.example.com/api/packages/testuser/nuget/symbols
```
## 安装软件包
要从软件包注册表安装 NuGet 软件包，请执行以下命令：
```shell
dotnet add package --source {source_name} --version {package_version} {package_name}
```
| 参数 | 描述 |
| ----------------- | ------------ |
| `source_name` | 所需源名称 |
| `package_name` | 软件包名称 |
| `package_version` | 软件包版本。 |
例如：
```shell
dotnet add package --source gitea --version 1.0.0 test_package
```
## 支持的命令
```
dotnet add
dotnet nuget push
dotnet nuget delete
```

109
docs/content/doc/usage/packages/overview.zh-cn.md Normal file
View File

@ -0,0 +1,109 @@
---
date: "2021-07-20T00:00:00+00:00"
title: "软件包注册表"
slug: "overview"
weight: 1
draft: false
toc: false
menu:
sidebar:
parent: "packages"
name: "Overview"
weight: 1
identifier: "packages-overview"
---
# 软件包注册表
从Gitea **1.17**版本开始，软件包注册表可以用作常见软件包管理器的公共或私有注册表。
**目录**
{{< toc >}}
## 支持的软件包管理器
目前支持以下软件包管理器：
| Name | Language | Package client |
| ------------------------------------------------------------------- | ---------- | ------------------------- |
| [Alpine]({{< relref "doc/usage/packages/alpine.zh-cn.md" >}}) | - | `apk` |
| [Cargo]({{< relref "doc/usage/packages/cargo.zh-cn.md" >}}) | Rust | `cargo` |
| [Chef]({{< relref "doc/usage/packages/chef.zh-cn.md" >}}) | - | `knife` |
| [Composer]({{< relref "doc/usage/packages/composer.zh-cn.md" >}}) | PHP | `composer` |
| [Conan]({{< relref "doc/usage/packages/conan.zh-cn.md" >}}) | C++ | `conan` |
| [Conda]({{< relref "doc/usage/packages/conda.zh-cn.md" >}}) | - | `conda` |
| [Container]({{< relref "doc/usage/packages/container.zh-cn.md" >}}) | - | 任何符合OCI规范的客户端 |
| [CRAN]({{< relref "doc/usage/packages/cran.zh-cn.md" >}}) | R | - |
| [Debian]({{< relref "doc/usage/packages/debian.zh-cn.md" >}}) | - | `apt` |
| [Generic]({{< relref "doc/usage/packages/generic.zh-cn.md" >}}) | - | 任何HTTP客户端 |
| [Go]({{< relref "doc/usage/packages/go.zh-cn.md" >}}) | Go | `go` |
| [Helm]({{< relref "doc/usage/packages/helm.zh-cn.md" >}}) | - | 任何HTTP客户端, `cm-push` |
| [Maven]({{< relref "doc/usage/packages/maven.zh-cn.md" >}}) | Java | `mvn`, `gradle` |
| [npm]({{< relref "doc/usage/packages/npm.zh-cn.md" >}}) | JavaScript | `npm`, `yarn`, `pnpm` |
| [NuGet]({{< relref "doc/usage/packages/nuget.zh-cn.md" >}}) | .NET | `nuget` |
| [Pub]({{< relref "doc/usage/packages/pub.zh-cn.md" >}}) | Dart | `dart`, `flutter` |
| [PyPI]({{< relref "doc/usage/packages/pypi.zh-cn.md" >}}) | Python | `pip`, `twine` |
| [RPM]({{< relref "doc/usage/packages/rpm.zh-cn.md" >}}) | - | `yum`, `dnf` |
| [RubyGems]({{< relref "doc/usage/packages/rubygems.zh-cn.md" >}}) | Ruby | `gem`, `Bundler` |
| [Swift]({{< relref "doc/usage/packages/rubygems.zh-cn.md" >}}) | Swift | `swift` |
| [Vagrant]({{< relref "doc/usage/packages/vagrant.zh-cn.md" >}}) | - | `vagrant` |
**以下段落仅适用于未全局禁用软件包的情况！**
## 仓库 x 软件包
软件包始终属于所有者（用户或组织），而不是仓库。
要将（已上传的）软件包链接到仓库，请打开该软件包的设置页面，并选择要将此软件包链接到的仓库。
将链接到整个软件包，而不仅是单个版本。
链接软件包将导致在仓库的软件包列表中显示该软件包，并在软件包页面上显示到仓库的链接（以及到仓库工单的链接）。
## 访问限制
| 软件包所有者类型 | 用户 | 组织 |
| ---------------- | ---------------------------------------- | ------------------------------------------ |
| **读取** 访问 | 公开，如果用户也是公开的；否则仅限此用户 | 公开，如果组织是公开的，否则仅限组织成员 |
| **写入** 访问 | 仅软件包所有者 | 具有组织中的管理员或写入访问权限的组织成员 |
注意：这些访问限制可能会[变化](https://github.com/go-gitea/gitea/issues/19270)，将通过专门的组织团队权限添加更细粒度的控制。
## 创建或上传软件包
根据软件包类型，使用相应的软件包管理器。请查看特定软件包管理器的子页面以获取说明。
## 查看软件包
您可以在仓库页面上查看仓库的软件包。
1. 转到仓库主页。
2. 在导航栏中选择**软件包**
要查看有关软件包的更多详细信息，请选择软件包的名称。
## 下载软件包
要从仓库下载软件包：
1. 在导航栏中选择**软件包**
2. 选择软件包的名称以查看详细信息。
3. 在 **Assets** 部分，选择要下载的软件包文件的名称。
## 删除软件包
在将软件包发布到软件包注册表后，您无法编辑软件包。相反，您必须删除并重新创建它。
要从仓库中删除软件包：
1. 在导航栏中选择**软件包**
2. 选择软件包的名称以查看详细信息。
3. 单击**删除软件包**以永久删除软件包。
## 禁用软件包注册表
包注册表已自动启用。要在单个存储库中禁用它：
1. 在导航栏中选择**设置**。
2. 禁用**启用仓库软件包注册表**.
禁用软件包注册表不会删除先前发布的软件包。

4
docs/content/doc/usage/packages/pub.en-us.md
View File

@ -1,6 +1,6 @@
---
date: "2022-07-31T00:00:00+00:00"
title: "Pub Packages Repository"
title: "Pub Package Registry"
slug: "pub"
weight: 90
draft: false
@ -13,7 +13,7 @@ menu:
identifier: "pub"
---
# Pub Packages Repository
# Pub Package Registry
Publish [Pub](https://dart.dev/guides/packages) packages for your user or organization.

84
docs/content/doc/usage/packages/pub.zh-cn.md Normal file
View File

@ -0,0 +1,84 @@
---
date: "2022-07-31T00:00:00+00:00"
title: "Pub 软件包注册表"
slug: "pub"
weight: 90
draft: false
toc: false
menu:
sidebar:
parent: "packages"
name: "Pub"
weight: 90
identifier: "pub"
---
# Pub 软件包注册表
为您的用户或组织发布 [Pub](https://dart.dev/guides/packages) 软件包。
**目录**
{{< toc >}}
## 要求
要使用Pub软件包注册表，您需要使用 [dart](https://dart.dev/tools/dart-tool) 和/或 [flutter](https://docs.flutter.dev/reference/flutter-cli). 工具。
以下示例使用 `dart`。
## 配置软件包注册表
要注册软件包注册表并提供凭据，请执行以下操作：
```shell
dart pub token add https://gitea.example.com/api/packages/{owner}/pub
```
| 占位符 | 描述 |
| ------- | -------------- |
| `owner` | 软件包的所有者 |
您需要提供您的[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})。
## 发布软件包
要发布软件包，请编辑 `pubspec.yaml` 文件，并添加以下行：
```yaml
publish_to: https://gitea.example.com/api/packages/{owner}/pub
```
| 占位符 | 描述 |
| ------- | -------------- |
| `owner` | 软件包的所有者 |
现在，您可以通过运行以下命令来发布软件包：
```shell
dart pub publish
```
如果已存在具有相同名称和版本的软件包，则无法发布软件包。您必须先删除现有的软件包。
## 安装软件包
要从软件包注册表安装Pub软件包，请执行以下命令：
```shell
dart pub add {package_name} --hosted-url=https://gitea.example.com/api/packages/{owner}/pub/
```
| 参数 | 描述 |
| -------------- | -------------- |
| `owner` | 软件包的所有者 |
| `package_name` | 软件包名称 |
例如：
```shell
# use latest version
dart pub add mypackage --hosted-url=https://gitea.example.com/api/packages/testuser/pub/
# specify version
dart pub add mypackage:1.0.8 --hosted-url=https://gitea.example.com/api/packages/testuser/pub/
```

4
docs/content/doc/usage/packages/pypi.en-us.md
View File

@ -1,6 +1,6 @@
---
date: "2021-07-20T00:00:00+00:00"
title: "PyPI Packages Repository"
title: "PyPI Package Registry"
slug: "pypi"
weight: 100
draft: false
@ -13,7 +13,7 @@ menu:
identifier: "pypi"
---
# PyPI Packages Repository
# PyPI Package Registry
Publish [PyPI](https://pypi.org/) packages for your user or organization.

88
docs/content/doc/usage/packages/pypi.zh-cn.md Normal file
View File

@ -0,0 +1,88 @@
---
date: "2021-07-20T00:00:00+00:00"
title: "PyPI 软件包注册表"
slug: "pypi"
weight: 100
draft: false
toc: false
menu:
sidebar:
parent: "packages"
name: "PyPI"
weight: 100
identifier: "pypi"
---
# PyPI 软件包注册表
为您的用户或组织发布 [PyPI](https://pypi.org/) 软件包。
**目录**
{{< toc >}}
## 要求
要使用 PyPI 软件包注册表，您需要使用 [pip](https://pypi.org/project/pip/) 工具来消费和使用 [twine](https://pypi.org/project/twine/) 工具来发布软件包。
## 配置软件包注册表
要注册软件包注册表，您需要编辑本地的 `~/.pypirc` 文件。添加以下内容：
```ini
[distutils]
index-servers = gitea
[gitea]
repository = https://gitea.example.com/api/packages/{owner}/pypi
username = {username}
password = {password}
```
| 占位符 | 描述 |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `owner` | 软件包的所有者 |
| `username` | 您的 Gitea 用户名 |
| `password` | 您的 Gitea 密码。如果您使用 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码 |
## 发布软件包
通过运行以下命令来发布软件包：
```shell
python3 -m twine upload --repository gitea /path/to/files/*
```
软件包文件的扩展名为 `.tar.gz` 和 `.whl`。
如果已存在具有相同名称和版本的软件包，则无法发布软件包。您必须先删除现有的软件包。
## 安装软件包
要从软件包注册表安装 PyPI 软件包，请执行以下命令：
```shell
pip install --index-url https://{username}:{password}@gitea.example.com/api/packages/{owner}/pypi/simple --no-deps {package_name}
```
| 参数 | 描述 |
| -------------- | ----------------------------- |
| `username` | 您的 Gitea 用户名 |
| `password` | 您的 Gitea 密码或个人访问令牌 |
| `owner` | 软件包的所有者 |
| `package_name` | 软件包名称 |
例如：
```shell
pip install --index-url https://testuser:password123@gitea.example.com/api/packages/testuser/pypi/simple --no-deps test_package
```
您可以使用 `--extra-index-url` 替代 `--index-url`，但这样会使您容易受到依赖混淆攻击，因为 `pip` 会先检查官方 PyPi 仓库中的软件包，然后再检查指定的自定义仓库。请阅读 `pip` 文档以获取更多信息。
## 支持的命令
```
pip install
twine upload
```

6
docs/content/doc/usage/packages/rpm.en-us.md
View File

@ -1,7 +1,7 @@
---
date: "2023-03-08T00:00:00+00:00"
title: "RPM Packages Repository"
slug: "packages/rpm"
title: "RPM Package Registry"
slug: "rpm"
draft: false
toc: false
menu:
@ -12,7 +12,7 @@ menu:
identifier: "rpm"
---
# RPM Packages Repository
# RPM Package Registry
Publish [RPM](https://rpm.org/) packages for your user or organization.

117
docs/content/doc/usage/packages/rpm.zh-cn.md Normal file
View File

@ -0,0 +1,117 @@
---
date: "2023-03-08T00:00:00+00:00"
title: "RPM 软件包注册表"
slug: "packages/rpm"
draft: false
toc: false
menu:
sidebar:
parent: "packages"
name: "RPM"
weight: 105
identifier: "rpm"
---
# RPM 软件包注册表
为您的用户或组织发布 [RPM](https://rpm.org/) 软件包。
**目录**
{{< toc >}}
## 要求
要使用RPM注册表，您需要使用像 `yum` 或 `dnf` 这样的软件包管理器来消费软件包。
以下示例使用 `dnf`。
## 配置软件包注册表
要注册RPM注册表，请将 URL 添加到已知 `apt` 源列表中：
```shell
dnf config-manager --add-repo https://gitea.example.com/api/packages/{owner}/rpm.repo
```
| 占位符 | 描述 |
| ------- | -------------- |
| `owner` | 软件包的所有者 |
如果注册表是私有的，请在URL中提供凭据。您可以使用密码或[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})：
```shell
dnf config-manager --add-repo https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/rpm.repo
```
您还必须将凭据添加到 `/etc/yum.repos.d` 中的 `rpm.repo` 文件中的URL中。
## 发布软件包
要发布RPM软件包（`*.rpm`），请执行带有软件包内容的 HTTP `PUT` 操作。
```
PUT https://gitea.example.com/api/packages/{owner}/rpm/upload
```
| 参数 | 描述 |
| ------- | -------------- |
| `owner` | 软件包的所有者 |
使用HTTP基本身份验证的示例请求：
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/file.rpm \
https://gitea.example.com/api/packages/testuser/rpm/upload
```
如果您使用 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码。您无法将具有相同名称的文件两次发布到软件包中。您必须先删除现有的软件包版本。
服务器将以以下HTTP状态码响应。
| HTTP 状态码 | 含义 |
| ----------------- | ------------------------------------------------ |
| `201 Created` | 软件包已发布 |
| `400 Bad Request` | 软件包无效 |
| `409 Conflict` | 具有相同参数组合的软件包文件已经存在于该软件包中 |
## 删除软件包
要删除 RPM 软件包，请执行 HTTP `DELETE` 操作。如果没有文件剩余，这也将删除软件包版本。
```
DELETE https://gitea.example.com/api/packages/{owner}/rpm/{package_name}/{package_version}/{architecture}
```
| 参数 | 描述 |
| ----------------- | -------------- |
| `owner` | 软件包的所有者 |
| `package_name` | 软件包名称 |
| `package_version` | 软件包版本 |
| `architecture` | 软件包架构 |
使用HTTP基本身份验证的示例请求：
```shell
curl --user your_username:your_token_or_password -X DELETE \
https://gitea.example.com/api/packages/testuser/rpm/test-package/1.0.0/x86_64
```
服务器将以以下HTTP状态码响应：
| HTTP 状态码 | 含义 |
| ---------------- | ------------------ |
| `204 No Content` | 成功 |
| `404 Not Found` | 未找到软件包或文件 |
## 安装软件包
要从RPM注册表安装软件包，请执行以下命令：
```shell
# use latest version
dnf install {package_name}
# use specific version
dnf install {package_name}-{package_version}.{architecture}
```

4
docs/content/doc/usage/packages/rubygems.en-us.md
View File

@ -1,6 +1,6 @@
---
date: "2021-07-20T00:00:00+00:00"
title: "RubyGems Packages Repository"
title: "RubyGems Package Registry"
slug: "rubygems"
weight: 110
draft: false
@ -13,7 +13,7 @@ menu:
identifier: "rubygems"
---
# RubyGems Packages Repository
# RubyGems Package Registry
Publish [RubyGems](https://guides.rubygems.org/) packages for your user or organization.

128
docs/content/doc/usage/packages/rubygems.zh-cn.md Normal file
View File

@ -0,0 +1,128 @@
---
date: "2021-07-20T00:00:00+00:00"
title: "RubyGems 软件包注册表"
slug: "rubygems"
weight: 110
draft: false
toc: false
menu:
sidebar:
parent: "packages"
name: "RubyGems"
weight: 110
identifier: "rubygems"
---
# RubyGems 软件包注册表
为您的用户或组织发布 [RubyGems](https://guides.rubygems.org/) 软件包。
**目录**
{{< toc >}}
## 要求
要使用RubyGems软件包注册表，您需要使用 [gem](https://guides.rubygems.org/command-reference/) 命令行工具来消费和发布软件包。
## 配置软件包注册表
要注册软件包注册表，请编辑 `~/.gem/credentials` 文件并添加：
```ini
---
https://gitea.example.com/api/packages/{owner}/rubygems: Bearer {token}
```
| 参数 | 描述 |
| ------- | ------------------------------------------------------------------------------------- |
| `owner` | 软件包的所有者 |
| `token` | 您的[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}}) |
例如：
```
---
https://gitea.example.com/api/packages/testuser/rubygems: Bearer 3bd626f84b01cd26b873931eace1e430a5773cc4
```
## 发布软件包
通过运行以下命令来发布软件包：
```shell
gem push --host {host} {package_file}
```
| 参数 | 描述 |
| -------------- | ------------------------ |
| `host` | 软件包注册表的URL |
| `package_file` | 软件包 `.gem` 文件的路径 |
例如：
```shell
gem push --host https://gitea.example.com/api/packages/testuser/rubygems test_package-1.0.0.gem
```
如果已经存在相同名称和版本的软件包，您将无法发布软件包。您必须先删除现有的软件包。
## 安装软件包
要从软件包注册表安装软件包，您可以使用 [Bundler](https://bundler.io) 或 `gem`。
### Bundler
在您的 `Gemfile` 中添加一个新的 `source` 块：
```
source "https://gitea.example.com/api/packages/{owner}/rubygems" do
gem "{package_name}"
end
```
| 参数 | 描述 |
| -------------- | -------------- |
| `owner` | 软件包的所有者 |
| `package_name` | 软件包名称 |
例如：
```
source "https://gitea.example.com/api/packages/testuser/rubygems" do
gem "test_package"
end
```
之后运行以下命令：
```shell
bundle install
```
### gem
执行以下命令：
```shell
gem install --host https://gitea.example.com/api/packages/{owner}/rubygems {package_name}
```
| 参数 | 描述 |
| -------------- | -------------- |
| `owner` | 软件包的所有者 |
| `package_name` | 软件包名称 |
例如：
```shell
gem install --host https://gitea.example.com/api/packages/testuser/rubygems test_package
```
## 支持的命令
```
gem install
bundle install
gem push
```

12
docs/content/doc/usage/packages/storage.en-us.md
View File

@ -77,9 +77,9 @@ The cleanup rules are part of the [clean up job]({{< relref "doc/administration/
The cleanup rule:
1. Collects all packages of the package type for the owners registry.
1. For every package it collects all versions.
1. Excludes from the list the # versions based on the *Keep the most recent* value.
1. Excludes from the list any versions matching the *Keep versions matching* value.
1. Excludes from the list the versions more recent than the *Remove versions older than* value.
1. Excludes from the list any versions not matching the *Remove versions matching* value.
1. Deletes the remaining versions.
2. For every package it collects all versions.
3. Excludes from the list the # versions based on the *Keep the most recent* value.
4. Excludes from the list any versions matching the *Keep versions matching* value.
5. Excludes from the list the versions more recent than the *Remove versions older than* value.
6. Excludes from the list any versions not matching the *Remove versions matching* value.
7. Deletes the remaining versions.

85
docs/content/doc/usage/packages/storage.zh-cn.md Normal file
View File

@ -0,0 +1,85 @@
---
date: "2022-11-01T00:00:00+00:00"
title: "存储"
slug: "storage"
weight: 5
draft: false
toc: false
menu:
sidebar:
parent: "packages"
name: "Storage"
weight: 2
identifier: "storage"
---
# 存储
本文档描述了软件包注册表的存储方式以及如何管理存储。
**目录**
{{< toc >}}
## 去重
软件包注册表具有内置的去重功能，可以对上传的 Blob 进行去重处理。
如果上传了两个相同的文件，只会在文件系统上保存一个 Blob。
这样可以确保不会浪费空间用于重复的文件。
如果上传了两个具有相同文件的软件包，这两个软件包将显示相同的大小，但在文件系统上，它们只需要一半的大小。
每当删除一个软件包时，只会删除对底层 Blob 的引用。
此时，Blob 不会被删除，因此它们仍然占用文件系统上的空间。
当上传新的软件包时，现有的 Blob 可能会再次被引用。
这些无引用的 Blob 会在一个清理任务中被删除。
配置设置 `OLDER_THAN` 可以配置无引用的 Blob 在被删除之前保留的时间。
## 清理规则
软件包注册表可能会随着时间的推移而变得很大，如果不进行清理的话。
建议删除不必要的软件包并设置清理规则以自动管理软件包注册表的使用情况。
每个软件包所有者（用户或组织）都可以管理应用于其软件包的清理规则。
| 设置 | 描述 |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| 启用 | 打开或关闭清理规则。 |
| 类型 | 每个规则管理特定的软件包类型。 |
| 将模式应用于完整的软件包名称 | 如果启用，则应用以下模式到完整的软件包名称（`package/version`），否则只使用版本号（`version`）。 |
| 保留最近的版本数 | 对于每个软件包要始终保留的版本数量。 |
| 保留与以下模式匹配的版本 | 确定要保留哪些版本的正则表达式模式。空模式表示不保留任何版本，而 `.+` 表示保留所有版本。即使未配置，容器注册表也始终保留 `latest` 版本。 |
| 删除早于多少天的版本 | 仅删除早于所选天数的版本。 |
| 删除与以下模式匹配的版本 | 确定要删除哪些版本的正则表达式模式。空模式或 `.+` 表示如果没有其他设置指定，则删除所有软件包。 |
每个清理规则都可以显示受影响的软件包的预览。
这可以用来检查清理规则是否正确配置。
### 正则表达式示例
正则表达式模式会自动使用 `\A` 和 `\z` 锚点进行包围。
不要在正则表达式模式中包含任何 `\A`、`\z`、`^` 或 `$` 标记，因为它们不是必要的。
模式是不区分大小写的，与 Gitea 中的软件包注册表的行为相匹配。
| Pattern | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `.*` | 匹配任何可能的版本。 |
| `v.+` | 匹配以 `v` 开头的版本。 |
| `release` | 仅匹配版本号为 `release`。 |
| `release.*` | 匹配以 `release` 命名或以 `release` 开头的版本。 |
| `.+-temp-.+` | 匹配包含 `-temp-` 的版本。 |
| `v.+\|release` | 匹配以 `v` 开头的版本或版本号为 `release`。 |
| `package/v.+\|other/release` | 匹配以 `v` 开头的 package 的版本或 `other` 的版本号为 `release`。需要启用*将模式应用于完整的软件包名称*设置。 |
### 清理规则的工作原理
清理规则是清理任务的一部分，定期运行。
清理规则：
1. 收集所有属于所有者注册表的特定软件包类型的软件包。
2. 对于每个软件包，收集所有版本。
3. 根据 *保留最近的版本数* 的值，从列表中排除版本。
4. 根据 *保留与以下模式匹配的版本* 的值，从列表中排除任何版本。
5. 根据 *删除早于多少天的版本* 的值，从列表中排除比这个值更近的版本。
6. 根据 *删除与以下模式匹配的版本* 的值，从列表中排除任何不匹配的版本。
7. 删除剩余的版本。

4
docs/content/doc/usage/packages/swift.en-us.md
View File

@ -1,6 +1,6 @@
---
date: "2023-01-10T00:00:00+00:00"
title: "Swift Packages Repository"
title: "Swift Package Registry"
slug: "swift"
weight: 95
draft: false
@ -13,7 +13,7 @@ menu:
identifier: "swift"
---
# Swift Packages Repository
# Swift Package Registry
Publish [Swift](https://www.swift.org/) packages for your user or organization.

94
docs/content/doc/usage/packages/swift.zh-cn.md Normal file
View File

@ -0,0 +1,94 @@
---
date: "2023-01-10T00:00:00+00:00"
title: "Swift 软件包注册表"
slug: "swift"
weight: 95
draft: false
toc: false
menu:
sidebar:
parent: "packages"
name: "Swift"
weight: 95
identifier: "swift"
---
# Swift 软件包注册表
为您的用户或组织发布 [Swift](https://www.swift.org/) 软件包。
**目录**
{{< toc >}}
## 要求
要使用 Swift 软件包注册表，您需要使用 [swift](https://www.swift.org/getting-started/) 消费软件包，并使用 HTTP 客户端（如 `curl`）发布软件包。
## 配置软件包注册表
要注册软件包注册表并提供凭据，请执行以下命令：
```shell
swift package-registry set https://gitea.example.com/api/packages/{owner}/swift -login {username} -password {password}
```
| 占位符 | 描述 |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `owner` | 软件包的所有者。 |
| `username` | 您的 Gitea 用户名。 |
| `password` | 您的 Gitea 密码。如果您使用两步验证或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})代替密码。 |
登录是可选的，只有在软件包注册表是私有的情况下才需要。
## 发布软件包
首先，您需要打包软件包的内容：
```shell
swift package archive-source
```
要发布软件包，请执行一个带有软件包内容的 HTTP `PUT` 请求，将内容放在请求正文中。
```shell --user your_username:your_password_or_token \
curl -X PUT --user {username}:{password} \
-H "Accept: application/vnd.swift.registry.v1+json" \
-F source-archive=@/path/to/package.zip \
-F metadata={metadata} \
https://gitea.example.com/api/packages/{owner}/swift/{scope}/{name}/{version}
```
| 占位符 | 描述 |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `username` | 您的 Gitea 用户名。 |
| `password` | 您的 Gitea 密码。如果您使用两步验证或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})代替密码。 |
| `owner` | 软件包的所有者。 |
| `scope` | 软件包的作用域。 |
| `name` | 软件包的名称。 |
| `version` | 软件包的版本。 |
| `metadata` | （可选）软件包的元数据。以 JSON 编码的子集，格式参考 https://schema.org/SoftwareSourceCode |
如果已经存在相同名称和版本的软件包，则无法发布软件包。您必须首先删除现有的软件包。
## 安装软件包
要从软件包注册表安装 Swift 软件包，请将其添加到 `Package.swift` 文件的依赖项列表中：
```
dependencies: [
.package(id: "{scope}.{name}", from:"{version}")
]
```
| 参数 | 描述 |
| --------- | -------------- |
| `scope` | 软件包的作用域 |
| `name` | 软件包的名称 |
| `version` | 软件包的版本 |
之后，执行以下命令来安装它：
```shell
swift package resolve
```

4
docs/content/doc/usage/packages/vagrant.en-us.md
View File

@ -1,6 +1,6 @@
---
date: "2022-08-23T00:00:00+00:00"
title: "Vagrant Packages Repository"
title: "Vagrant Package Registry"
slug: "vagrant"
weight: 120
draft: false
@ -13,7 +13,7 @@ menu:
identifier: "vagrant"
---
# Vagrant Packages Repository
# Vagrant Package Registry
Publish [Vagrant](https://www.vagrantup.com/) packages for your user or organization.

Some files were not shown because too many files have changed in this diff Show More