diff --git a/docs/content/doc/administration/adding-legal-pages.zh-cn.md b/docs/content/doc/administration/adding-legal-pages.zh-cn.md new file mode 100644 index 0000000000..dc0bccef3d --- /dev/null +++ b/docs/content/doc/administration/adding-legal-pages.zh-cn.md @@ -0,0 +1,40 @@ +--- +date: "2023-05-23T09:00:00+08:00" +title: "添加法律页面" +slug: adding-legal-pages +weight: 110 +toc: false +draft: false +aliases: + - /zh-cn/adding-legal-pages +menu: + sidebar: + parent: "administration" + name: "添加法律页面" + identifier: "adding-legal-pages" + weight: 110 +--- + +一些法域(例如欧盟)要求在网站上添加特定的法律页面(例如隐私政策)。按照以下步骤将它们添加到你的 Gitea 实例中。 + +## 获取页面 + +Gitea 源代码附带了示例页面,位于 `contrib/legal` 目录中。将它们复制到 `custom/public/` 目录下。例如,如果要添加隐私政策: + +``` +wget -O /path/to/custom/public/privacy.html https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/legal/privacy.html.sample +``` + +现在,你需要编辑该页面以满足你的需求。特别是,你必须更改电子邮件地址、网址以及与 "Your Gitea Instance" 相关的引用,以匹配你的情况。 + +请务必不要放置会暗示 Gitea 项目对你的服务器负责的一般服务条款或隐私声明。 + +## 使其可见 + +创建或追加到 `/path/to/custom/templates/custom/extra_links_footer.tmpl` 文件中: + +```go +隐私政策 +``` + +重启 Gitea 以查看更改。 diff --git a/docs/content/doc/administration/cmd-embedded.zh-cn.md b/docs/content/doc/administration/cmd-embedded.zh-cn.md new file mode 100644 index 0000000000..663d9cdada --- /dev/null +++ b/docs/content/doc/administration/cmd-embedded.zh-cn.md @@ -0,0 +1,105 @@ +--- +date: "2023-05-23T09:00:00+08:00" +title: "嵌入资源提取工具" +slug: "cmd-embedded" +weight: 20 +toc: false +draft: false +aliases: + - /zh-cn/cmd-embedded +menu: + sidebar: + parent: "administration" + name: "嵌入资源提取工具" + weight: 20 + identifier: "cmd-embedded" +--- + +# 嵌入资源提取工具 + +**目录** + +{{< toc >}} + +Gitea 的可执行文件包含了运行所需的所有资源:模板、图片、样式表和翻译文件。你可以通过在 `custom` 目录下的相应路径中放置替换文件来覆盖其中的任何资源(详见 [自定义 Gitea 配置]({{< relref "doc/administration/customizing-gitea.zh-cn.md" >}}))。 + +要获取嵌入资源的副本以进行编辑,可以使用 CLI 中的 `embedded` 命令,通过操作系统的 shell 执行。 + +**注意:** 嵌入资源提取工具包含在 Gitea 1.12 及以上版本中。 + +## 资源列表 + +要列出嵌入在 Gitea 可执行文件中的资源,请使用以下语法: + +```sh +gitea embedded list [--include-vendored] [patterns...] +``` + +`--include-vendored` 标志使命令包括被供应的文件,这些文件通常被排除在外;即来自外部库的文件,这些文件是 Gitea 所需的(例如 [octicons](https://octicons.github.com/) 等)。 + +可以提供一系列文件搜索模式。Gitea 使用 [gobwas/glob](https://github.com/gobwas/glob) 作为其 glob 语法。以下是一些示例: + +- 列出所有模板文件,无论在哪个虚拟目录下:`**.tmpl` +- 列出所有邮件模板文件:`templates/mail/**.tmpl` +- 列出 `public/img` 目录下的所有文件:`public/img/**` + +不要忘记为模式使用引号,因为空格、`*` 和其他字符可能对命令行解释器有特殊含义。 + +如果未提供模式,则列出所有文件。 + +### 示例 + +列出所有路径中包含 `openid` 的嵌入文件: + +```sh +$ gitea embedded list '**openid**' +public/img/auth/openid_connect.svg +public/img/openid-16x16.png +templates/user/auth/finalize_openid.tmpl +templates/user/auth/signin_openid.tmpl +templates/user/auth/signup_openid_connect.tmpl +templates/user/auth/signup_openid_navbar.tmpl +templates/user/auth/signup_openid_register.tmpl +templates/user/settings/security_openid.tmpl +``` + +## 提取资源 + +要提取嵌入在 Gitea 可执行文件中的资源,请使用以下语法: + +```sh +gitea [--config {file}] embedded extract [--destination {dir}|--custom] [--overwrite|--rename] [--include-vendored] {patterns...} +``` + +`--config` 选项用于告知 Gitea `app.ini` 配置文件的位置(如果不在默认位置)。此选项仅在使用 `--custom` 标志时使用。 + +`--destination` 选项用于指定提取文件的目标目录。默认为当前目录。 + +`--custom` 标志告知 Gitea 直接将文件提取到 `custom` 目录中。为使其正常工作,该命令需要知道 `app.ini` 配置文件的位置(通过 `--config` 指定),并且根据配置的不同,需要从 Gitea 通常启动的目录运行。有关详细信息,请参阅 [自定义 Gitea 配置]({{< relref "doc/administration/customizing-gitea.zh-cn.md" >}})。 + +`--overwrite` 标志允许覆盖目标目录中的任何现有文件。 + +`--rename` 标志告知 Gitea 将目标目录中的任何现有文件重命名为 `filename.bak`。之前的 `.bak` 文件将被覆盖。 + +至少需要提供一个文件搜索模式;有关模式的语法和示例,请参阅上述 `list` 子命令。 + +### 重要提示 + +请确保**只提取需要自定义的文件**。位于 `custom` 目录中的文件不会受到 Gitea 的升级过程的影响。当 Gitea 升级到新版本(通过替换可执行文件)时,许多嵌入文件将发生变化。Gitea 将尊重并使用在 `custom` 目录中找到的任何文件,即使这些文件是旧的和不兼容的。 + +### 示例 + +将邮件模板提取到临时目录: + +```sh +$ mkdir tempdir +$ gitea embedded extract --destination tempdir 'templates/mail/**.tmpl' +Extracting to tempdir: +tempdir/templates/mail/auth/activate.tmpl +tempdir/templates/mail/auth/activate_email.tmpl +tempdir/templates/mail/auth/register_notify.tmpl +tempdir/templates/mail/auth/reset_passwd.tmpl +tempdir/templates/mail/issue/assigned.tmpl +tempdir/templates/mail/issue/default.tmpl +tempdir/templates/mail/notify/collaborator.tmpl +``` diff --git a/docs/content/doc/administration/command-line.zh-cn.md b/docs/content/doc/administration/command-line.zh-cn.md new file mode 100644 index 0000000000..c05e95d36a --- /dev/null +++ b/docs/content/doc/administration/command-line.zh-cn.md @@ -0,0 +1,556 @@ +--- +date: "2023-05-23T09:00:00+08:00" +title: "Gitea 命令行" +slug: "command-line" +weight: 1 +toc: false +draft: false +aliases: + - /zh-cn/command-line +menu: + sidebar: + parent: "administration" + name: "Gitea 命令行" + weight: 1 + identifier: "command-line" +--- + +# 命令行 + +**目录** + +{{< toc >}} + +## 用法 + +`gitea [全局选项] 命令 [命令或全局选项] [参数...]` + +## 全局选项 + +所有全局选项均可被放置在命令级别。 + +- `--help`,`-h`:显示帮助文本并退出。可选。 +- `--version`,`-v`:显示版本信息并退出。可选。 (示例:`Gitea version 1.1.0+218-g7b907ed built with: bindata, sqlite`)。 +- `--custom-path path`,`-C path`:Gitea 自定义文件夹的路径。可选。 (默认值:`AppWorkPath`/custom 或 `$GITEA_CUSTOM`)。 +- `--config path`,`-c path`:Gitea 配置文件的路径。可选。 (默认值:`custom`/conf/app.ini)。 +- `--work-path path`,`-w path`:Gitea 的 `AppWorkPath`。可选。 (默认值:LOCATION_OF_GITEA_BINARY 或 `$GITEA_WORK_DIR`) + +注意:默认的 custom-path、config 和 work-path 也可以在构建时更改(如果需要)。 + +## 命令 + +### web + +启动服务器: + +- 选项: + - `--port number`,`-p number`:端口号。可选。 (默认值:3000)。覆盖配置文件中的设置。 + - `--install-port number`:运行安装页面的端口号。可选。 (默认值:3000)。覆盖配置文件中的设置。 + - `--pid path`,`-P path`:Pid 文件的路径。可选。 + - `--quiet`,`-q`:只在控制台上输出 Fatal 日志,用于在设置日志之前发出的日志。 + - `--verbose`:在控制台上输出跟踪日志,用于在设置日志之前发出的日志。 +- 示例: + - `gitea web` + - `gitea web --port 80` + - `gitea web --config /etc/gitea.ini --pid /some/custom/gitea.pid` +- 注意: + - Gitea 不应以 root 用户身份运行。要绑定到低于 1024 的端口,您可以在 Linux 上使用 setcap 命令:`sudo setcap 'cap_net_bind_service=+ep' /path/to/gitea`。每次更新 Gitea 都需要重新执行此操作。 + +### admin + +管理员操作: + +- 命令: + - `user`: + - `list`: + - 选项: + - `--admin`:仅列出管理员用户。可选。 + - 描述:列出所有现有用户。 + - 示例: + - `gitea admin user list` + - `delete`: + - 选项: + - `--email`:要删除的用户的电子邮件。 + - `--username`:要删除的用户的用户名。 + - `--id`:要删除的用户的ID。 + - 必须提供 `--id`、`--username` 或 `--email` 中的一个。如果提供多个,则所有条件必须匹配。 + - 示例: + - `gitea admin user delete --id 1` + - `create`: + - 选项: + - `--name value`:用户名。必填。自 Gitea 1.9.0 版本起,请改用 `--username` 标志。 + - `--username value`:用户名。必填。Gitea 1.9.0 新增。 + - `--password value`:密码。必填。 + - `--email value`:邮箱。必填。 + - `--admin`:如果提供此选项,将创建一个管理员用户。可选。 + - `--access-token`:如果提供,将为用户创建访问令牌。可选。(默认值:false)。 + - `--must-change-password`:如果提供,创建的用户将在初始登录后需要选择一个新密码。可选。(默认值:true)。 + - `--random-password`:如果提供,将使用随机生成的密码作为创建用户的密码。`--password` 的值将被忽略。可选。 + - `--random-password-length`:如果提供,将用于配置随机生成密码的长度。可选。(默认值:12) + - 示例: + - `gitea admin user create --username myname --password asecurepassword --email me@example.com` + - `change-password`: + - 选项: + - `--username value`,`-u value`:用户名。必填。 + - `--password value`,`-p value`:新密码。必填。 + - 示例: + - `gitea admin user change-password --username myname --password asecurepassword` + - `must-change-password`: + - 参数: + - `[username...]`:需要更改密码的用户 + - 选项: + - `--all`,`-A`:强制所有用户更改密码 + - `--exclude username`,`-e username`:排除给定的用户。可以多次设置。 + - `--unset`:撤销对给定用户的强制密码更改 + - `regenerate`: + - 选项: + - `hooks`:重新生成所有仓库的 Git Hooks。 + - `keys`:重新生成 authorized_keys 文件。 + - 示例: + - `gitea admin regenerate hooks` + - `gitea admin regenerate keys` + - `auth`: + - `list`: + - 描述:列出所有存在的外部认证源。 + - 示例: + - `gitea admin auth list` + - `delete`: + - 选项: + - `--id`:要删除的源的 ID。必填。 + - 示例: + - `gitea admin auth delete --id 1` + - `add-oauth`: + - 选项: + - `--name`:应用程序名称。 + - `--provider`:OAuth2 提供者。 + - `--key`:客户端 ID(Key)。 + - `--secret`:客户端密钥。 + - `--auto-discover-url`:OpenID Connect 自动发现 URL(仅在使用 OpenID Connect 作为提供程序时需要)。 + - `--use-custom-urls`:在 GitLab/GitHub OAuth 端点上使用自定义 URL。 + - `--custom-tenant-id`:在 OAuth 端点上使用自定义租户 ID。 + - `--custom-auth-url`:使用自定义授权 URL(GitLab/GitHub 的选项)。 + - `--custom-token-url`:使用自定义令牌 URL(GitLab/GitHub 的选项)。 + - `--custom-profile-url`:使用自定义配置文件 URL(GitLab/GitHub 的选项)。 + - `--custom-email-url`:使用自定义电子邮件 URL(GitHub 的选项)。 + - `--icon-url`:OAuth2 登录源的自定义图标 URL。 + - `--skip-local-2fa`:允许源覆盖本地 2FA。(可选) + - `--scopes`:请求此 OAuth2 源的附加范围。(可选) + - `--required-claim-name`:必须设置的声明名称,以允许用户使用此源登录。(可选) + - `--required-claim-value`:必须设置的声明值,以允许用户使用此源登录。(可选) + - `--group-claim-name`:提供此源的组名的声明名称。(可选) + - `--admin-group`:管理员用户的组声明值。(可选) + - `--restricted-group`:受限用户的组声明值。(可选) + - `--group-team-map`:组与组织团队之间的 JSON 映射。(可选) + - `--group-team-map-removal`:根据组自动激活团队成员资格的删除。(可选) + - 示例: + - `gitea admin auth add-oauth --name external-github --provider github --key OBTAIN_FROM_SOURCE --secret OBTAIN_FROM_SOURCE` + - `update-oauth`: + - 选项: + - `--id`:要更新的源的 ID。必填。 + - `--name`:应用程序名称。 + - `--provider`:OAuth2 提供者。 + - `--key`:客户端 ID(Key)。 + - `--secret`:客户端密钥。 + - `--auto-discover-url`:OpenID Connect 自动发现 URL(仅在使用 OpenID Connect 作为提供程序时需要)。 + - `--use-custom-urls`:在 GitLab/GitHub OAuth 端点上使用自定义 URL。 + - `--custom-tenant-id`:在 OAuth 端点上使用自定义租户 ID。 + - `--custom-auth-url`:使用自定义授权 URL(GitLab/GitHub 的选项)。 + - `--custom-token-url`:使用自定义令牌 URL(GitLab/GitHub 的选项)。 + - `--custom-profile-url`:使用自定义配置文件 URL(GitLab/GitHub 的选项)。 + - `--custom-email-url`:使用自定义电子邮件 URL(GitHub 的选项)。 + - `--icon-url`:OAuth2 登录源的自定义图标 URL。 + - `--skip-local-2fa`:允许源覆盖本地 2FA。(可选) + - `--scopes`:请求此 OAuth2 源的附加范围。 + - `--required-claim-name`:必须设置的声明名称,以允许用户使用此源登录。(可选) + - `--required-claim-value`:必须设置的声明值,以允许用户使用此源登录。(可选) + - `--group-claim-name`:提供此源的组名的声明名称。(可选) + - `--admin-group`:管理员用户的组声明值。(可选) + - `--restricted-group`:受限用户的组声明值。(可选) + - 示例: + - `gitea admin auth update-oauth --id 1 --name external-github-updated` + - `add-smtp`: + - 选项: + - `--name`:应用程序名称。必填。 + - `--auth-type`:SMTP 认证类型(PLAIN/LOGIN/CRAM-MD5)。默认为 PLAIN。 + - `--host`:SMTP 主机。必填。 + - `--port`:SMTP 端口。必填。 + - `--force-smtps`:SMTPS 始终在端口 465 上使用。设置此选项以强制在其他端口上使用 SMTPS。 + - `--skip-verify`:跳过 TLS 验证。 + - `--helo-hostname`:发送 HELO 时使用的主机名。留空以发送当前主机名。 + - `--disable-helo`:禁用 SMTP helo。 + - `--allowed-domains`:留空以允许所有域。使用逗号(',')分隔多个域。 + - `--skip-local-2fa`:跳过 2FA 登录。 + - `--active`:启用此认证源。 + 备注: + `--force-smtps`、`--skip-verify`、`--disable-helo`、`--skip-local-2fs` 和 `--active` 选项可以采用以下形式使用: + - `--option`、`--option=true` 以启用选项 + - `--option=false` 以禁用选项 + 如果未指定这些选项,则在 `update-smtp` 中不会更改值,或者在 `add-smtp` 中将使用默认的 `false` 值。 + - 示例: + - `gitea admin auth add-smtp --name ldap --host smtp.mydomain.org --port 587 --skip-verify --active` + - `update-smtp`: + - 选项: + - `--id`:要更新的源的 ID。必填。 + - 其他选项与 `add-smtp` 共享 + - 示例: + - `gitea admin auth update-smtp --id 1 --host smtp.mydomain.org --port 587 --skip-verify=false` + - `gitea admin auth update-smtp --id 1 --active=false` + - `add-ldap`:添加新的 LDAP(通过 Bind DN)认证源 + - 选项: + - `--name value`:认证名称。必填。 + - `--not-active`:停用认证源。 + - `--security-protocol value`:安全协议名称。必填。 + - `--skip-tls-verify`:禁用 TLS 验证。 + - `--host value`:LDAP 服务器的地址。必填。 + - `--port value`:连接到 LDAP 服务器时使用的端口。必填。 + - `--user-search-base value`:用户帐户将在其中搜索的 LDAP 基础路径。必填。 + - `--user-filter value`:声明如何查找试图进行身份验证的用户记录的 LDAP 过滤器。必填。 + - `--admin-filter value`:指定是否应授予用户管理员特权的 LDAP 过滤器。 + - `--restricted-filter value`:指定是否应将用户设置为受限状态的 LDAP 过滤器。 + - `--username-attribute value`:用户 LDAP 记录中包含用户名的属性。 + - `--firstname-attribute value`:用户 LDAP 记录中包含用户名字的属性。 + - `--surname-attribute value`:用户 LDAP 记录中包含用户姓氏的属性。 + - `--email-attribute value`:用户 LDAP 记录中包含用户电子邮件地址的属性。必填。 + - `--public-ssh-key-attribute value`:用户 LDAP 记录中包含用户公共 SSH 密钥的属性。 + - `--avatar-attribute value`:用户 LDAP 记录中包含用户头像的属性。 + - `--bind-dn value`:在搜索用户时绑定到 LDAP 服务器的 DN。 + - `--bind-password value`:绑定 DN 的密码(如果有)。 + - `--attributes-in-bind`:在绑定 DN 上下文中获取属性。 + - `--synchronize-users`:启用用户同步。 + - `--page-size value`:搜索页面大小。 + - 示例: + - `gitea admin auth add-ldap --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-search-base "ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))" --email-attribute mail` + - `update-ldap`:更新现有的 LDAP(通过 Bind DN)认证源 + - 选项: + - `--id value`:认证源的 ID。必填。 + - `--name value`:认证名称。 + - `--not-active`:停用认证源。 + - `--security-protocol value`:安全协议名称。 + - `--skip-tls-verify`:禁用 TLS 验证。 + - `--host value`:LDAP 服务器的地址。 + - `--port value`:连接到 LDAP 服务器时使用的端口。 + - `--user-search-base value`:用户帐户将在其中搜索的 LDAP 基础路径。 + - `--user-filter value`:声明如何查找试图进行身份验证的用户记录的 LDAP 过滤器。 + - `--admin-filter value`:指定是否应授予用户管理员特权的 LDAP 过滤器。 + - `--restricted-filter value`:指定是否应将用户设置为受限状态的 LDAP 过滤器。 + - `--username-attribute value`:用户 LDAP 记录中包含用户名的属性。 + - `--firstname-attribute value`:用户 LDAP 记录中包含用户名字的属性。 + - `--surname-attribute value`:用户 LDAP 记录中包含用户姓氏的属性。 + - `--email-attribute value`:用户 LDAP 记录中包含用户电子邮件地址的属性。 + - `--public-ssh-key-attribute value`:用户 LDAP 记录中包含用户公共 SSH 密钥的属性。 + - `--avatar-attribute value`:用户 LDAP 记录中包含用户头像的属性。 + - `--bind-dn value`:在搜索用户时绑定到 LDAP 服务器的 DN。 + - `--bind-password value`:绑定 DN 的密码(如果有)。 + - `--attributes-in-bind`:在绑定 DN 上下文中获取属性。 + - `--synchronize-users`:启用用户同步。 + - `--page-size value`:搜索页面大小。 + - 示例: + - `gitea admin auth update-ldap --id 1 --name "my ldap auth source"` + - `gitea admin auth update-ldap --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn` + - `add-ldap-simple`:添加新的 LDAP(简单身份验证)认证源 + - 选项: + - `--name value`:认证名称。必填。 + - `--not-active`:停用认证源。 + - `--security-protocol value`:安全协议名称。必填。 + - `--skip-tls-verify`:禁用 TLS 验证。 + - `--host value`:LDAP 服务器的地址。必填。 + - `--port value`:连接到 LDAP 服务器时使用的端口。必填。 + - `--user-search-base value`:用户帐户将在其中搜索的 LDAP 基础路径。 + - `--user-filter value`:声明如何查找试图进行身份验证的用户记录的 LDAP 过滤器。必填。 + - `--admin-filter value`:指定是否应授予用户管理员特权的 LDAP 过滤器。 + - `--restricted-filter value`:指定是否应将用户设置为受限状态的 LDAP 过滤器。 + - `--username-attribute value`:用户 LDAP 记录中包含用户名的属性。 + - `--firstname-attribute value`:用户 LDAP 记录中包含用户名字的属性。 + - `--surname-attribute value`:用户 LDAP 记录中包含用户姓氏的属性。 + - `--email-attribute value`:用户 LDAP 记录中包含用户电子邮件地址的属性。必填。 + - `--public-ssh-key-attribute value`:用户 LDAP 记录中包含用户公共 SSH 密钥的属性。 + - `--avatar-attribute value`:用户 LDAP 记录中包含用户头像的属性。 + - `--user-dn value`:用户的 DN。必填。 + - 示例: + - `gitea admin auth add-ldap-simple --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-dn "cn=%s,ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(cn=%s))" --email-attribute mail` + - `update-ldap-simple`:更新现有的 LDAP(简单身份验证)认证源 + - 选项: + - `--id value`:认证源的 ID。必填。 + - `--name value`:认证名称。 + - `--not-active`:停用认证源。 + - `--security-protocol value`:安全协议名称。 + - `--skip-tls-verify`:禁用 TLS 验证。 + - `--host value`:LDAP 服务器的地址。 + - `--port value`:连接到 LDAP 服务器时使用的端口。 + - `--user-search-base value`:用户帐户将在其中搜索的 LDAP 基础路径。 + - `--user-filter value`:声明如何查找试图进行身份验证的用户记录的 LDAP 过滤器。 + - `--admin-filter value`:指定是否应授予用户管理员特权的 LDAP 过滤器。 + - `--restricted-filter value`:指定是否应将用户设置为受限状态的 LDAP 过滤器。 + - `--username-attribute value`:用户 LDAP 记录中包含用户名的属性。 + - `--firstname-attribute value`:用户 LDAP 记录中包含用户名字的属性。 + - `--surname-attribute value`:用户 LDAP 记录中包含用户姓氏的属性。 + - `--email-attribute value`:用户 LDAP 记录中包含用户电子邮件地址的属性。 + - `--public-ssh-key-attribute value`:用户 LDAP 记录中包含用户公共 SSH 密钥的属性。 + - `--avatar-attribute value`:用户 LDAP 记录中包含用户头像的属性。 + - `--user-dn value`:用户的 DN。 + - 示例: + - `gitea admin auth update-ldap-simple --id 1 --name "my ldap auth source"` + - `gitea admin auth update-ldap-simple --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn` + +### cert + +生成自签名的SSL证书。将输出到当前目录下的`cert.pem`和`key.pem`文件中,并且会覆盖任何现有文件。 + +- 选项: + - `--host value`:逗号分隔的主机名和IP地址列表,此证书适用于这些主机。支持使用通配符。必填。 + - `--ecdsa-curve value`:用于生成密钥的ECDSA曲线。可选。有效选项为P224、P256、P384、P521。 + - `--rsa-bits value`:要生成的RSA密钥的大小。可选。如果设置了--ecdsa-curve,则忽略此选项。(默认值:2048)。 + - `--start-date value`:证书的创建日期。可选。(格式:`Jan 1 15:04:05 2011`)。 + - `--duration value`:证书有效期。可选。(默认值:8760h0m0s) + - `--ca`:如果提供此选项,则证书将生成自己的证书颁发机构。可选。 +- 示例: + - `gitea cert --host git.example.com,example.com,www.example.com --ca` + +### dump + +将所有文件和数据库导出到一个zip文件中。输出文件将保存在当前目录下,类似于`gitea-dump-1482906742.zip`。 + +- 选项: + - `--file name`,`-f name`:指定要创建的导出文件的名称。可选。(默认值:gitea-dump-[timestamp].zip)。 + - `--tempdir path`,`-t path`:指定临时目录的路径。可选。(默认值:/tmp)。 + - `--skip-repository`,`-R`:跳过仓库的导出。可选。 + - `--skip-custom-dir`:跳过自定义目录的导出。可选。 + - `--skip-lfs-data`:跳过LFS数据的导出。可选。 + - `--skip-attachment-data`:跳过附件数据的导出。可选。 + - `--skip-package-data`:跳过包数据的导出。可选。 + - `--skip-log`:跳过日志数据的导出。可选。 + - `--database`,`-d`:指定数据库的SQL语法。可选。 + - `--verbose`,`-V`:如果提供此选项,显示附加详细信息。可选。 + - `--type`:设置导出的格式。可选。(默认值:zip) +- 示例: + - `gitea dump` + - `gitea dump --verbose` + +### generate + +用于在配置文件中生成随机值和令牌。对于自动部署时生成值非常有用。 + +- 命令: + - `secret`: + - 选项: + - `INTERNAL_TOKEN`: 用于内部 API 调用身份验证的令牌。 + - `JWT_SECRET`: 用于 LFS 和 OAUTH2 JWT 身份验证的密钥(LFS_JWT_SECRET 是此选项的别名,用于向后兼容)。 + - `SECRET_KEY`: 全局密钥。 + - 示例: + - `gitea generate secret INTERNAL_TOKEN` + - `gitea generate secret JWT_SECRET` + - `gitea generate secret SECRET_KEY` + +### keys + +提供一个 SSHD AuthorizedKeysCommand。需要在 sshd 配置文件中进行配置: + +```ini +... +# -e 的值和 AuthorizedKeysCommandUser 应与运行 Gitea 的用户名匹配 +AuthorizedKeysCommandUser git +AuthorizedKeysCommand /path/to/gitea keys -e git -u %u -t %t -k %k +``` + +该命令将返回适用于提供的密钥的合适 authorized_keys 行。您还应在 `app.ini` 的 `[server]` 部分设置值 `SSH_CREATE_AUTHORIZED_KEYS_FILE=false`。 + +注意: opensshd 要求 Gitea 程序由 root 拥有,并且不可由组或其他人写入。程序必须使用绝对路径指定。 +注意: Gitea 必须在运行此命令时处于运行状态才能成功。 + +### migrate + +迁移数据库。该命令可用于在首次启动服务器之前运行其他命令。此命令是幂等的。 + +### convert + +将现有的 MySQL 数据库从 utf8 转换为 utf8mb4。 + +### doctor + +根据给定的配置诊断当前 Gitea 实例的问题。目前有以下检查清单: + +- 检查 OpenSSH 的 authorized_keys 文件是否正确 + 当您的 Gitea 实例支持 OpenSSH 时,当您的 Gitea 实例添加或更改任何公钥时,Gitea 实例的二进制路径将被写入 `authorized_keys` 文件。 + 有时,如果您在升级时移动或重命名了 Gitea 二进制文件,并且您没有在管理面板上运行“使用 Gitea 的 SSH 密钥更新「.ssh/authorized_keys」文件”操作。那么通过 SSH 的所有拉取/推送操作将无法正常工作。 + 此检查将帮助您检查它是否正常工作。 + +对于贡献者,如果您想添加更多的检查项,您可以编写一个新的函数,如 `func(ctx *cli.Context) ([]string, error)`,并将其追加到 `doctor.go` 文件中。 + +```go +var checklist = []check{ + { + title: "Check if OpenSSH authorized_keys file id correct", + f: runDoctorLocationMoved, + }, + // more checks please append here +} +``` + +此函数将接收一个命令行上下文,并返回有关问题或错误的详细信息列表。 + +#### doctor recreate-table + +有时,在迁移时,旧的列和默认值可能会在数据库模式中保持不变。这可能会导致警告,如下所示: + +``` +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 doctor recreate-table table1 table2 ... +``` + +如果您希望 Gitea 重新创建所有表,请直接调用: + +``` +gitea doctor recreate-table +``` + +强烈建议在运行这些命令之前备份您的数据库。 + +### manager + +管理运行中的服务器操作: + +- 命令: + - `shutdown`: 优雅地关闭运行中的进程 + - `restart`: 优雅地重新启动运行中的进程(对于Windows服务器尚未实现) + - `flush-queues`: 刷新运行中的进程中的队列 + - 选项: + - `--timeout value`: 刷新过程的超时时间(默认值: 1m0s) + - `--non-blocking`: 设置为true,以在返回之前不等待刷新完成 + - `logging`: 调整日志命令 + - 命令: + - `pause`: 暂停日志记录 + - 注意: + - 如果日志级别低于此级别,日志级别将被临时提升为INFO。 + - Gitea将在一定程度上缓冲日志,并在超过该点后丢弃日志。 + - `resume`: 恢复日志记录 + - `release-and-reopen`: 使Gitea释放和重新打开用于日志记录的文件和连接(相当于向Gitea发送SIGUSR1信号)。 + - `remove name`: 删除指定的日志记录器 + - 选项: + - `--group group`, `-g group`: 从中删除子记录器的组(默认为`default`) + - `add`: 添加日志记录器 + - 命令: + - `console`: 添加控制台日志记录器 + - 选项: + - `--group value`, `-g value`: 要添加日志记录器的组 - 默认为"default" + - `--name value`, `-n value`: 新日志记录器的名称 - 默认为模式 + - `--level value`, `-l value`: 新日志记录器的日志级别 + - `--stacktrace-level value`, `-L value`: 堆栈跟踪日志级别 + - `--flags value`, `-F value`: 日志记录器的标志 + - `--expression value`, `-e value`: 日志记录器的匹配表达式 + - `--prefix value`, `-p value`: 日志记录器的前缀 + - `--color`: 在日志中使用颜色 + - `--stderr`: 将控制台日志输出到stderr - 仅适用于控制台 + - `file`: 添加文件日志记录器 + - 选项: + - `--group value`, `-g value`: 要添加日志记录器的组 - 默认为"default" + - `--name value`, `-n value`: 新日志记录器的名称 - 默认为模式 + - `--level value`, `-l value`: 新日志记录器的日志级别 + - `--stacktrace-level value`, `-L value`: 堆栈跟踪日志级别 + - `--flags value`, `-F value`: 日志记录器的标志 + - `--expression value`, `-e value`: 日志记录器的匹配表达式 + - `--prefix value`, `-p value`: 日志记录器的前缀 + - `--color`: 在日志中使用颜色 + - `--filename value`, `-f value`: 日志记录器的文件名 + - `--rotate`, `-r`: 轮转日志 + - `--max-size value`, `-s value`: 在轮转之前的最大大小(以字节为单位) + - `--daily`, `-d`: 每天轮转日志 + - `--max-days value`, `-D value`: 保留的每日日志的最大数量 + - `--compress`, `-z`: 压缩轮转的日志 + - `--compression-level value`, `-Z value`: 使用的压缩级别 + - `conn`: 添加网络连接日志记录器 + - 选项: + - `--group value`, `-g value`: 要添加日志记录器的组 - 默认为"default" + - `--name value`, `-n value`: 新日志记录器的名称 - 默认为模式 + - `--level value`, `-l value`: 新日志记录器的日志级别 + - `--stacktrace-level value`, `-L value`: 堆栈跟踪日志级别 + - `--flags value`, `-F value`: 日志记录器的标志 + - `--expression value`, `-e value`: 日志记录器的匹配表达式 + - `--prefix value`, `-p value`: 日志记录器的前缀 + - `--color`: 在日志中使用颜色 + - `--reconnect-on-message`, `-R`: 对于每个消息重新连接主机 + - `--reconnect`, `-r`: 连接中断时重新连接主机 + - `--protocol value`, `-P value`: 设置要使用的协议:tcp、unix或udp(默认为tcp) + - `--address value`, `-a value`: 要连接到的主机地址和端口(默认为:7020) + - `smtp`: 添加SMTP日志记录器 + - 选项: + - `--group value`, `-g value`: 要添加日志记录器的组 - 默认为"default" + - `--name value`, `-n value`: 新日志记录器的名称 - 默认为模式 + - `--level value`, `-l value`: 新日志记录器的日志级别 + - `--stacktrace-level value`, `-L value`: 堆栈跟踪日志级别 + - `--flags value`, `-F value`: 日志记录器的标志 + - `--expression value`, `-e value`: 日志记录器的匹配表达式 + - `--prefix value`, `-p value`: 日志记录器的前缀 + - `--color`: 在日志中使用颜色 + - `--username value`, `-u value`: 邮件服务器用户名 + - `--password value`, `-P value`: 邮件服务器密码 + - `--host value`, `-H value`: 邮件服务器主机(默认为: 127.0.0.1:25) + - `--send-to value`, `-s value`: 要发送到的电子邮件地址 + - `--subject value`, `-S value`: 发送电子邮件的主题标题 + - `processes`: 显示 Gitea 进程和 Goroutine 信息 + - 选项: + - `--flat`: 以平面表格形式显示进程,而不是树形结构 + - `--no-system`: 不显示系统进程 + - `--stacktraces`: 显示与进程关联的 Goroutine 的堆栈跟踪 + - `--json`: 输出为 JSON 格式 + - `--cancel PID`: 向具有 PID 的进程发送取消命令(仅适用于非系统进程) + +### dump-repo + +`dump-repo` 从 Git/GitHub/Gitea/GitLab 中转储存储库数据: + +- 选项: + - `--git_service service`:Git 服务,可以是 `git`、`github`、`gitea`、`gitlab`。如果 `clone_addr` 可以被识别,则可以忽略此选项。 + - `--repo_dir dir`,`-r dir`:存储数据的存储库目录路径。 + - `--clone_addr addr`:将被克隆的 URL,目前可以是 git/github/gitea/gitlab 的 http/https URL。例如:https://github.com/lunny/tango.git + - `--auth_username lunny`:访问 `clone_addr` 的用户名。 + - `--auth_password `:访问 `clone_addr` 的密码。 + - `--auth_token `:访问 `clone_addr` 的个人令牌。 + - `--owner_name lunny`:如果非空,数据将存储在具有所有者名称的目录中。 + - `--repo_name tango`:如果非空,数据将存储在具有存储库名称的目录中。 + - `--units `:要迁移的项目,一个或多个项目应以逗号分隔。允许的项目有 wiki, issues, labels, releases, release_assets, milestones, pull_requests, comments。如果为空,则表示所有项目。 + +### restore-repo + +`restore-repo` 从磁盘目录中还原存储库数据: + +- 选项: + - `--repo_dir dir`,`-r dir`:还原数据的存储库目录路径。 + - `--owner_name lunny`:还原目标所有者名称。 + - `--repo_name tango`:还原目标存储库名称。 + - `--units `:要还原的项目,一个或多个项目应以逗号分隔。允许的项目有 wiki, issues, labels, releases, release_assets, milestones, pull_requests, comments。如果为空,则表示所有项目。 + +### actions generate-runner-token + +生成一个供 Runner 使用的新令牌,用于向服务器注册。 + +- 选项: + - `--scope {owner}[/{repo}]`,`-s {owner}[/{repo}]`:限制 Runner 的范围,没有范围表示该 Runner 可用于所有仓库,但你也可以将其限制为特定的仓库或所有者。 + +要注册全局 Runner: + +``` +gitea actions generate-runner-token +``` + +要注册特定组织的 Runner,例如 `org`: + +``` +gitea actions generate-runner-token -s org +``` + +要注册特定仓库的 Runner,例如 `username/test-repo`: + +``` +gitea actions generate-runner-token -s username/test-repo +``` diff --git a/docs/content/doc/administration/email-setup.zh-cn.md b/docs/content/doc/administration/email-setup.zh-cn.md new file mode 100644 index 0000000000..0bbeebf2f6 --- /dev/null +++ b/docs/content/doc/administration/email-setup.zh-cn.md @@ -0,0 +1,91 @@ +--- +date: "2023-05-23T09:00:00+08:00" +title: "Email 设置" +slug: "email-setup" +weight: 12 +toc: false +draft: false +aliases: + - /zh-cn/email-setup +menu: + sidebar: + parent: "administration" + name: "Email 设置" + weight: 12 + identifier: "email-setup" +--- + +# Email 设置 + +**目录** + +{{< toc >}} + +Gitea 具有邮件功能,用于发送事务性邮件(例如注册确认邮件)。它可以配置为使用 Sendmail(或兼容的 MTA,例如 Postfix 和 msmtp)或直接使用 SMTP 服务器。 + +## 使用 Sendmail + +使用 `sendmail` 命令作为邮件传输代理(mailer)。 + +注意:对于在官方Gitea Docker镜像中使用,请使用SMTP版本进行配置(请参考下一节)。 + +注意:对于面向互联网的网站,请查阅您的 MTA 文档以了解通过TLS发送邮件的说明。同时设置 SPF、DMARC 和 DKIM DNS 记录,以使发送的邮件被各个电子邮件提供商接受为合法邮件。 + +```ini +[mailer] +ENABLED = true +FROM = gitea@mydomain.com +MAILER_TYPE = sendmail +SENDMAIL_PATH = /usr/sbin/sendmail +SENDMAIL_ARGS = "--" ; 大多数 "sendmail" 程序都接受选项,使用 "--" 将防止电子邮件地址被解释为选项。 +``` + +## 使用 SMTP + +直接使用 SMTP 服务器作为中继。如果您不想在实例上设置 MTA,但在电子邮件提供商那里有一个帐户,这个选项非常有用。 + +```ini +[mailer] +ENABLED = true +FROM = gitea@mydomain.com +MAILER_TYPE = smtp +SMTP_ADDR = mail.mydomain.com +SMTP_PORT = 587 +IS_TLS_ENABLED = true +USER = gitea@mydomain.com +PASSWD = `password` +``` + +重启 Gitea 以使配置更改生效。 + +要发送测试邮件以验证设置,请转到 Gitea > 站点管理 > 配置 > SMTP 邮件配置。 + +有关所有选项的完整列表,请查看[配置速查表](doc/administration/config-cheat-sheet.zh-cn.md)。 + +请注意:只有在使用 TLS 或 `HOST=localhost` 加密 SMTP 服务器通信时才支持身份验证。TLS 加密可以通过以下方式进行: + +- 通过端口 587 的 STARTTLS(也称为 Opportunistic TLS)。初始连接是明文的,但如果服务器支持,则可以升级为 TLS。 +- 通过默认端口 465 的 SMTPS 连接。连接到服务器从一开始就使用 TLS。 +- 使用 `IS_TLS_ENABLED=true` 进行强制的 SMTPS 连接。(这两种方式都被称为 Implicit TLS) +这是由于 Go 内部库对 STRIPTLS 攻击的保护机制。 + +请注意,自2018年起,[RFC8314](https://tools.ietf.org/html/rfc8314#section-3) 推荐使用 Implicit TLS。 + +### Gmail + +以下配置应该适用于 Gmail 的 SMTP 服务器: + +```ini +[mailer] +ENABLED = true +HOST = smtp.gmail.com:465 ; 对于 Gitea >= 1.18.0,删除此行 +SMTP_ADDR = smtp.gmail.com +SMTP_PORT = 465 +FROM = example.user@gmail.com +USER = example.user +PASSWD = `***` +MAILER_TYPE = smtp +IS_TLS_ENABLED = true +``` + +请注意,您需要创建并使用一个 [应用密码](https://support.google.com/accounts/answer/185833?hl=en) 并在您的 Google 帐户上启用 2FA。您将无法直接使用您的 Google 帐户密码。 diff --git a/docs/content/doc/administration/external-renderers.zh-cn.md b/docs/content/doc/administration/external-renderers.zh-cn.md new file mode 100644 index 0000000000..26d3fb45d3 --- /dev/null +++ b/docs/content/doc/administration/external-renderers.zh-cn.md @@ -0,0 +1,207 @@ +--- +date: "2023-05-23T09:00:00+08:00" +title: "外部渲染器" +slug: "external-renderers" +weight: 60 +toc: false +draft: false +aliases: + - /zh-cn/external-renderers +menu: + sidebar: + parent: "administration" + name: "外部渲染器" + weight: 60 + identifier: "external-renderers" +--- + +# 自定义文件渲染配置 + +**目录** + +{{< toc >}} + +Gitea 通过外部二进制文件支持自定义文件渲染(例如 Jupyter notebooks、asciidoc 等),只需要进行以下步骤: + +- 安装外部二进制文件 +- 在您的 `app.ini` 文件中添加一些配置 +- 重新启动 Gitea 实例 + +此功能支持整个文件的渲染。如果您想要在 Markdown 中渲染代码块,您需要使用 JavaScript 进行一些操作。请参阅 [自定义 Gitea 配置]({{< relref "doc/administration/customizing-gitea.zh-cn.md" >}}) 页面上的一些示例。 + +## 安装外部二进制文件 + +为了通过外部二进制文件进行文件渲染,必须安装它们的关联软件包。 +如果您正在使用 Docker 镜像,则您的 `Dockerfile` 应该包含以下内容: + +```docker +FROM gitea/gitea:{{< version >}} +[...] + +COPY custom/app.ini /data/gitea/conf/app.ini +[...] + +RUN apk --no-cache add asciidoctor freetype freetype-dev gcc g++ libpng libffi-dev py-pip python3-dev py3-pip py3-pyzmq +# 安装其他您需要的外部渲染器的软件包 + +RUN pip3 install --upgrade pip +RUN pip3 install -U setuptools +RUN pip3 install jupyter docutils +# 在上面添加您需要安装的任何其他 Python 软件包 +``` + +## `app.ini` 文件配置 + +在您的自定义 `app.ini` 文件中为每个外部渲染器添加一个 `[markup.XXXXX]` 部分: + +```ini +[markup.asciidoc] +ENABLED = true +FILE_EXTENSIONS = .adoc,.asciidoc +RENDER_COMMAND = "asciidoctor -s -a showtitle --out-file=- -" +; 输入不是标准输入而是文件 +IS_INPUT_FILE = false + +[markup.jupyter] +ENABLED = true +FILE_EXTENSIONS = .ipynb +RENDER_COMMAND = "jupyter nbconvert --stdin --stdout --to html --template basic" +IS_INPUT_FILE = false + +[markup.restructuredtext] +ENABLED = true +FILE_EXTENSIONS = .rst +RENDER_COMMAND = "timeout 30s pandoc +RTS -M512M -RTS -f rst" +IS_INPUT_FILE = false +``` + +如果您的外部标记语言依赖于在生成的 HTML 元素上的额外类和属性,您可能需要启用自定义的清理策略。Gitea 使用 [`bluemonday`](https://godoc.org/github.com/microcosm-cc/bluemonday) 包作为我们的 HTML 清理器。下面的示例可以用于支持从 [`pandoc`](https://pandoc.org/) 输出的服务器端 [KaTeX](https://katex.org/) 渲染结果。 + +```ini +[markup.sanitizer.TeX] +; Pandoc 渲染 TeX 段落为带有 "math" 类的 元素,根据上下文可能还带有 "inline" 或 "display" 类。 +; - 请注意,这与我们的 Markdown 解析器中内置的数学支持不同,后者使用 元素。 +ELEMENT = span +ALLOW_ATTR = class +REGEXP = ^\s*((math(\s+|$)|inline(\s+|$)|display(\s+|$)))+ + +[markup.markdown] +ENABLED = true +FILE_EXTENSIONS = .md,.markdown +RENDER_COMMAND = pandoc -f markdown -t html --katex +``` + +您必须在每个部分中定义 `ELEMENT` 和 `ALLOW_ATTR`。 + +要定义多个条目,请添加唯一的字母数字后缀(例如,`[markup.sanitizer.1]` 和 `[markup.sanitizer.something]`)。 + +要仅为特定的外部渲染器应用清理规则,它们必须使用渲染器名称,例如 `[markup.sanitizer.asciidoc.rule-1]`、`[markup.sanitizer..rule-1]`。 + +**注意**:如果规则在渲染器 ini 部分之前定义,或者名称与渲染器不匹配,它将应用于所有渲染器。 + +完成配置更改后,请重新启动 Gitea 以使更改生效。 + +**注意**:在 Gitea 1.12 之前,存在一个名为 `markup.sanitiser` 的单个部分,其中的键被重新定义为多个规则,但是,这种配置方法存在重大问题,需要通过多个部分进行配置。 + +### 示例:HTML + +直接渲染 HTML 文件: + +```ini +[markup.html] +ENABLED = true +FILE_EXTENSIONS = .html,.htm +RENDER_COMMAND = cat +; 输入不是标准输入,而是文件 +IS_INPUT_FILE = true + +[markup.sanitizer.html.1] +ELEMENT = div +ALLOW_ATTR = class + +[markup.sanitizer.html.2] +ELEMENT = a +ALLOW_ATTR = class +``` + +请注意:此示例中的配置将允许渲染 HTML 文件,并使用 `cat` 命令将文件内容输出为 HTML。此外,配置中的两个清理规则将允许 `
` 和 `` 元素使用 `class` 属性。 + +在进行配置更改后,请重新启动 Gitea 以使更改生效。 + +### 示例:Office DOCX + +使用 [`pandoc`](https://pandoc.org/) 显示 Office DOCX 文件: + +```ini +[markup.docx] +ENABLED = true +FILE_EXTENSIONS = .docx +RENDER_COMMAND = "pandoc --from docx --to html --self-contained --template /path/to/basic.html" + +[markup.sanitizer.docx.img] +ALLOW_DATA_URI_IMAGES = true +``` + +在此示例中,配置将允许显示 Office DOCX 文件,并使用 `pandoc` 命令将文件转换为 HTML 格式。同时,清理规则中的 `ALLOW_DATA_URI_IMAGES` 设置为 `true`,允许使用 Data URI 格式的图片。 + +模板文件的内容如下: + +``` +$body$ +``` + +### 示例:Jupyter Notebook + +使用 [`nbconvert`](https://github.com/jupyter/nbconvert) 显示 Jupyter Notebook 文件: + +```ini +[markup.jupyter] +ENABLED = true +FILE_EXTENSIONS = .ipynb +RENDER_COMMAND = "jupyter-nbconvert --stdin --stdout --to html --template basic" + +[markup.sanitizer.jupyter.img] +ALLOW_DATA_URI_IMAGES = true +``` + +在此示例中,配置将允许显示 Jupyter Notebook 文件,并使用 `nbconvert` 命令将文件转换为 HTML 格式。同样,清理规则中的 `ALLOW_DATA_URI_IMAGES` 设置为 `true`,允许使用 Data URI 格式的图片。 + +在进行配置更改后,请重新启动 Gitea 以使更改生效。 + +## 自定义 CSS + +在 `.ini` 文件中,可以使用 `[markup.XXXXX]` 的格式指定外部渲染器,并且由外部渲染器生成的 HTML 将被包装在一个带有 `markup` 和 `XXXXX` 类的 `
` 中。`markup` 类提供了预定义的样式(如果 `XXXXX` 是 `markdown`,则使用 `markdown` 类)。否则,您可以使用这些类来针对渲染的 HTML 内容进行定制样式。 + +因此,您可以编写一些 CSS 样式: + +```css +.markup.XXXXX html { + font-size: 100%; + overflow-y: scroll; + -webkit-text-size-adjust: 100%; + -ms-text-size-adjust: 100%; +} + +.markup.XXXXX body { + color: #444; + font-family: Georgia, Palatino, 'Palatino Linotype', Times, 'Times New Roman', serif; + font-size: 12px; + line-height: 1.7; + padding: 1em; + margin: auto; + max-width: 42em; + background: #fefefe; +} + +.markup.XXXXX p { + color: orangered; +} +``` + +将您的样式表添加到自定义目录中,例如 `custom/public/css/my-style-XXXXX.css`,并使用自定义的头文件 `custom/templates/custom/header.tmpl` 进行导入: + +```html + +``` + +通过以上步骤,您可以将自定义的 CSS 样式应用到特定的外部渲染器,使其具有所需的样式效果。 diff --git a/docs/content/doc/administration/git-lfs-support.zh-cn.md b/docs/content/doc/administration/git-lfs-support.zh-cn.md new file mode 100644 index 0000000000..247e9a4777 --- /dev/null +++ b/docs/content/doc/administration/git-lfs-support.zh-cn.md @@ -0,0 +1,32 @@ +--- +date: "2023-05-23T09:00:00+08:00" +title: "Git LFS 设置" +slug: "git-lfs-setup" +weight: 12 +toc: false +draft: false +aliases: + - /zh-cn/git-lfs-setup +menu: + sidebar: + parent: "administration" + name: "Git LFS 设置" + weight: 12 + identifier: "git-lfs-setup" +--- + +# 配置 Git 大文件存储(Large File Storage,LFS) + +要使用 Gitea 内置的 LFS 支持,您需要更新 `app.ini` 文件: + +```ini +[server] +; 启用 git-lfs 支持。true 或 false,默认为 false。 +LFS_START_SERVER = true + +[lfs] +; 存放 LFS 文件的路径,默认为 data/lfs。 +PATH = /home/gitea/data/lfs +``` + +**注意**:LFS 服务器支持需要服务器上安装 Git v2.1.2 以上版本。 diff --git a/docs/content/doc/administration/logging-config.zh-cn.md b/docs/content/doc/administration/logging-config.zh-cn.md new file mode 100644 index 0000000000..1edf1443cd --- /dev/null +++ b/docs/content/doc/administration/logging-config.zh-cn.md @@ -0,0 +1,276 @@ +--- +date: "2023-05-23T09:00:00+08:00" +title: "日志配置" +slug: "logging-config" +weight: 40 +toc: false +draft: false +aliases: + - /zh-cn/logging-configuration +menu: + sidebar: + parent: "administration" + name: "日志配置" + weight: 40 + identifier: "logging-config" +--- + +# 日志配置 + +Gitea 的日志配置主要由以下三种类型的组件组成: + +- `[log]` 部分用于一般配置 +- `[log.]` 部分用于配置不同的日志输出方式,也称为 "writer mode",模式名称同时也作为 "writer name" +- `[log]` 部分还可以包含遵循 `logger..` 模式的子日志记录器的配置 + +默认情况下,已经有一个完全功能的日志输出,因此不需要重新定义。 + +**目录** + +{{< toc >}} + +## 收集日志以获取帮助 + +要收集日志以获取帮助和报告问题,请参阅 [需要帮助]({{< relref "doc/help/support.zh-cn.md" >}})。 + +## `[log]` 部分 + +在 Gitea 中,日志设施的配置在 `[log]` 部分及其子部分。 + +在顶层的 `[log]` 部分,可以放置以下配置项: + +- `ROOT_PATH`:(默认值:**%(GITEA_WORK_DIR)/log**):日志文件的基本路径。 +- `MODE`:(默认值:**console**):要用于默认日志记录器的日志输出列表。 +- `LEVEL`:(默认值:**Info**):要持久化的最严重的日志事件,不区分大小写。可能的值为:`Trace`、`Debug`、`Info`、`Warn`、`Error`、`Fatal`。 +- `STACKTRACE_LEVEL`:(默认值:**None**):对于此类及更严重的事件,将在记录时打印堆栈跟踪。 + +它还可以包含以下子日志记录器: + +- `logger.router.MODE`:(默认值:**,**):用于路由器日志记录器的日志输出列表。 +- `logger.access.MODE`:(默认值:**\**):用于访问日志记录器的日志输出列表。默认情况下,访问日志记录器被禁用。 +- `logger.xorm.MODE`:(默认值:**,**):用于 XORM 日志记录器的日志输出列表。 + +将子日志记录器的模式设置为逗号(`,`)表示使用默认的全局 `MODE`。 + +## 快速示例 + +### 默认(空)配置 + +空配置等同于默认配置: + +```ini +[log] +ROOT_PATH = %(GITEA_WORK_DIR)/log +MODE = console +LEVEL = Info +STACKTRACE_LEVEL = None +logger.router.MODE = , +logger.xorm.MODE = , +logger.access.MODE = + +; 这是“控制台”模式的配置选项(由上面的 MODE=console 使用) +[log.console] +MODE = console +FLAGS = stdflags +PREFIX = +COLORIZE = true +``` + +这等同于将所有日志发送到控制台,并将默认的 Golang 日志也发送到控制台日志中。 + +这只是一个示例,默认情况下不需要将其写入配置文件中。 + +### 禁用路由日志并将一些访问日志记录到文件中 + +禁用路由日志,将访问日志(>=Warn)记录到 `access.log` 中: + +```ini +[log] +logger.router.MODE = +logger.access.MODE = access-file + +[log.access-file] +MODE = file +LEVEL = Warn +FILE_NAME = access.log +``` + +### 为不同的模式设置不同的日志级别 + +将默认日志(>=Warn)记录到 `gitea.log` 中,将错误日志记录到 `file-error.log` 中: + +```ini +[log] +LEVEL = Warn +MODE = file, file-error + +; 默认情况下,"file" 模式会将日志记录到 %(log.ROOT_PATH)/gitea.log,因此我们不需要设置它 +; [log.file] + +[log.file-error] +LEVEL = Error +FILE_NAME = file-error.log +``` + +## 日志输出(模式和写入器) + +Gitea 提供以下日志写入器: + +- `console` - 输出日志到 `stdout`(或 `stderr`,如果已在配置中设置) +- `file` - 输出日志到文件 +- `conn` - 输出日志到套接字(网络或 Unix 套接字) + +### 公共配置 + +某些配置适用于所有日志输出模式: + +- `MODE` 是日志输出写入器的模式。它将默认为 ini 部分的模式名称。因此,`[log.console]` 将默认为 `MODE = console`。 +- `LEVEL` 是此输出将记录的最低日志级别。 +- `STACKTRACE_LEVEL` 是此输出将打印堆栈跟踪的最低日志级别。 +- `COLORIZE` 对于 `console`,默认为 `true`,否则默认为 `false`。 + +#### `EXPRESSION` + +`EXPRESSION` 表示日志事件必须匹配才能被输出写入器记录的正则表达式。 +日志消息(去除颜色)或 `longfilename:linenumber:functionname` 必须匹配其中之一。 +注意:整个消息或字符串不需要完全匹配。 + +请注意,此表达式将在写入器的 goroutine 中运行,而不是在日志事件的 goroutine 中运行。 + +#### `FLAGS` + +`FLAGS` 表示在每条消息之前打印的前置日志上下文信息。 +它是一个逗号分隔的字符串集。值的顺序无关紧要。 + +默认值为 `stdflags`(= `date,time,medfile,shortfuncname,levelinitial`)。 + +可能的值为: + +- `none` 或 `,` - 无标志。 +- `date` - 当地时区的日期:`2009/01/23`。 +- `time` - 当地时区的时间:`01:23:23`。 +- `microseconds` - 微秒精度:`01:23:23.123123`。假定有时间。 +- `longfile` - 完整的文件名和行号:`/a/b/c/d.go:23`。 +- `shortfile` - 文件名的最后一个部分和行号:`d.go:23`。 +- `funcname` - 调用者的函数名:`runtime.Caller()`。 +- `shortfuncname` - 函数名的最后一部分。覆盖 `funcname`。 +- `utc` - 如果设置了日期或时间,则使用 UTC 而不是本地时区。 +- `levelinitial` - 提供的级别的初始字符,放在方括号内,例如 `[I]` 表示 info。 +- `level` - 在方括号内的级别,例如 `[INFO]`。 +- `gopid` - 上下文的 Goroutine-PID。 +- `medfile` - 文件名的最后 20 个字符 - 相当于 `shortfile,longfile`。 +- `stdflags` - 相当于 `date,time,medfile,shortfuncname,levelinitial`。 + +### Console 模式 + +在此模式下,日志记录器将将日志消息转发到 Gitea 进程附加的 stdout 和 stderr 流。 + +对于 console 模式的日志记录器,如果不在 Windows 上,或者 Windows 终端可以设置为 ANSI 模式,或者是 cygwin 或 Msys 管道,则 `COLORIZE` 默认为 `true`。 + +设置: + +- `STDERR`:**false**:日志记录器是否应将日志打印到 `stderr` 而不是 `stdout`。 + +### File 模式 + +在此模式下,日志记录器将将日志消息保存到文件中。 + +设置: + +- `FILE_NAME`:要将日志事件写入的文件,相对于 `ROOT_PATH`,默认为 `%(ROOT_PATH)/gitea.log`。异常情况:访问日志默认为 `%(ROOT_PATH)/access.log`。 +- `MAX_SIZE_SHIFT`:**28**:单个文件的最大大小位移。28 表示 256Mb。详细信息见下文。 +- `LOG_ROTATE` **true**:是否轮转日志文件。 +- `DAILY_ROTATE`:**true**:是否每天旋转日志。 +- `MAX_DAYS`:**7**:在此天数之后删除旋转的日志文件。 +- `COMPRESS`:**true**:默认情况下是否使用 gzip 压缩旧的日志文件。 +- `COMPRESSION_LEVEL`:**-1**:压缩级别。详细信息见下文。 + +`MAX_SIZE_SHIFT` 通过将给定次数左移 1 (`1 << x`) 来定义文件的最大大小。 +在 v1.17.3 版本时的确切行为可以在[这里](https://github.com/go-gitea/gitea/blob/v1.17.3/modules/setting/log.go#L185)中查看。 + +`COMPRESSION_LEVEL` 的有用值范围从 1 到(包括)9,其中较高的数字表示更好的压缩。 +请注意,更好的压缩可能会带来更高的资源使用。 +必须在前面加上 `-` 符号。 + +### Conn 模式 + +在此模式下,日志记录器将通过网络套接字发送日志消息。 + +设置: + +- `ADDR`:**:7020**:设置要连接的地址。 +- `PROTOCOL`:**tcp**:设置协议,可以是 "tcp"、"unix" 或 "udp"。 +- `RECONNECT`:**false**:在连接丢失时尝试重新连接。 +- `RECONNECT_ON_MSG`:**false**:为每条消息重新连接主机。 + +### "Router" 日志记录器 + +当 Gitea 的路由处理程序工作时,Router 日志记录器记录以下消息类型: + +- `started` 消息将以 TRACE 级别记录 +- `polling`/`completed` 路由将以 INFO 级别记录。异常情况:"/assets" 静态资源请求也会以 TRACE 级别记录。 +- `slow` 路由将以 WARN 级别记录 +- `failed` 路由将以 WARN 级别记录 + +### "XORM" 日志记录器 + +为了使 XORM 输出 SQL 日志,还应将 `[database]` 部分中的 `LOG_SQL` 设置为 `true`。 + +### "Access" 日志记录器 + +"Access" 日志记录器是自 Gitea 1.9 版本以来的新日志记录器。它提供了符合 NCSA Common Log 标准的日志格式。虽然它具有高度可配置性,但在更改其模板时应谨慎。此日志记录器的主要好处是,Gitea 现在可以使用标准日志格式记录访问日志,因此可以使用标准工具进行分析。 + +您可以通过使用 `logger.access.MODE = ...` 来启用此日志记录器。 + +如果需要,可以通过更改 `ACCESS_LOG_TEMPLATE` 的值来更改 "Access" 日志记录器的格式。 + +请注意,访问日志记录器将以 `INFO` 级别记录,将此日志记录器的 `LEVEL` 设置为 `WARN` 或更高级别将导致不记录访问日志。 + +#### ACCESS_LOG_TEMPLATE + +此值表示一个 Go 模板。其默认值为 + +```tmpl +{{.Ctx.RemoteHost}} - {{.Identity}} {{.Start.Format "[02/Jan/2006:15:04:05 -0700]" }} "{{.Ctx.Req.Method}} {{.Ctx.Req.URL.RequestURI}} {{.Ctx.Req.Proto}}" {{.ResponseWriter.Status}} {{.ResponseWriter.Size}} "{{.Ctx.Req.Referer}}" "{{.Ctx.Req.UserAgent}}"` +``` + +模板接收以下选项: + +- `Ctx` 是 `context.Context` +- `Identity` 是 `SignedUserName`,如果用户未登录,则为 "-" +- `Start` 是请求的开始时间 +- `ResponseWriter` 是 `http.ResponseWriter` + +更改此模板时必须小心,因为它在标准的 panic 恢复陷阱之外运行。此模板应该尽可能简单,因为它会为每个请求运行一次。 + +## 释放和重新打开、暂停和恢复日志记录 + +如果您在 Unix 上运行,您可能希望释放和重新打开日志以使用 `logrotate` 或其他工具。 +可以通过向运行中的进程发送 `SIGUSR1` 信号或运行 `gitea manager logging release-and-reopen` 命令来强制 Gitea 释放并重新打开其日志文件和连接。 + +或者,您可能希望暂停和恢复日志记录 - 可以通过使用 `gitea manager logging pause` 和 `gitea manager logging resume` 命令来实现。请注意,当日志记录暂停时,低于 INFO 级别的日志事件将不会存储,并且只会存储有限数量的事件。在暂停时,日志记录可能会阻塞,尽管是暂时性的,但会大大减慢 Gitea 的运行速度,因此建议仅暂停很短的时间。 + +### 在 Gitea 运行时添加和删除日志记录 + +可以使用 `gitea manager logging add` 和 `remove` 子命令在 Gitea 运行时添加和删除日志记录。 +此功能只能调整正在运行的日志系统,不能用于启动未初始化的访问或路由日志记录器。如果您希望启动这些系统,建议调整 app.ini 并(优雅地)重新启动 Gitea 服务。 + +这些命令的主要目的是在运行中的系统上轻松添加临时日志记录器,以便调查问题,因为重新启动可能会导致问题消失。 + +## 使用 `logrotate` 而不是内置的日志轮转 + +Gitea 包含内置的日志轮转功能,对于大多数部署来说应该已经足够了。但是,如果您想使用 `logrotate` 工具: + +- 在 `app.ini` 中将 `LOG_ROTATE` 设置为 `false`,禁用内置的日志轮转。 +- 安装 `logrotate`。 +- 根据部署要求配置 `logrotate`,有关配置语法细节,请参阅 `man 8 logrotate`。 + 在 `postrotate/endscript` 块中通过 `kill -USR1` 或 `kill -10` 向 `gitea` 进程本身发送 `USR1` 信号, + 或者运行 `gitea manager logging release-and-reopen`(使用适当的环境设置)。 + 确保配置适用于由 Gitea 日志记录器生成的所有文件,如上述部分所述。 +- 始终使用 `logrotate /etc/logrotate.conf --debug` 来测试您的配置。 +- 如果您正在使用 Docker 并从容器外部运行,您可以使用 + `docker exec -u $OS_USER $CONTAINER_NAME sh -c 'gitea manager logging release-and-reopen'` + 或 `docker exec $CONTAINER_NAME sh -c '/bin/s6-svc -1 /etc/s6/gitea/'`,或直接向 Gitea 进程本身发送 `USR1` 信号。 + +下一个 `logrotate` 作业将包括您的配置,因此不需要重新启动。 +您还可以立即使用 `logrotate /etc/logrotate.conf --force` 重新加载 `logrotate`。 diff --git a/docs/content/doc/administration/mail-templates.zh-cn.md b/docs/content/doc/administration/mail-templates.zh-cn.md new file mode 100644 index 0000000000..3b03090099 --- /dev/null +++ b/docs/content/doc/administration/mail-templates.zh-cn.md @@ -0,0 +1,265 @@ +--- +date: "2023-05-23T09:00:00+08:00" +title: "邮件模板" +slug: "mail-templates" +weight: 45 +toc: false +draft: false +aliases: + - /zh-cn/mail-templates +menu: + sidebar: + parent: "administration" + name: "邮件模板" + weight: 45 + identifier: "mail-templates" +--- + +# 邮件模板 + +**目录** + +{{< toc >}} + +为了定制特定操作的电子邮件主题和内容,可以使用模板来自定义 Gitea。这些功能的模板位于 [`custom` 目录](https://docs.gitea.io/en-us/customizing-gitea/) 下。 +如果没有自定义的替代方案,Gitea 将使用内部模板作为默认模板。 + +自定义模板在 Gitea 启动时加载。对它们的更改在 Gitea 重新启动之前不会被识别。 + +## 支持模板的邮件通知 + +目前,以下通知事件使用模板: + +| 操作名称 | 用途 | +| ----------- | ------------------------------------------------------------------------------------------------------------ | +| `new` | 创建了新的工单或合并请求。 | +| `comment` | 在现有工单或合并请求中创建了新的评论。 | +| `close` | 关闭了工单或合并请求。 | +| `reopen` | 重新打开了工单或合并请求。 | +| `review` | 在合并请求中进行审查的首要评论。 | +| `approve` | 对合并请求进行批准的首要评论。 | +| `reject` | 对合并请求提出更改请求的审查的首要评论。 | +| `code` | 关于合并请求的代码的单个评论。 | +| `assigned` | 用户被分配到工单或合并请求。 | +| `default` | 未包括在上述类别中的任何操作,或者当对应类别的模板不存在时使用的模板。 | + +特定消息类型的模板路径为: + +```sh +custom/templates/mail/{操作类型}/{操作名称}.tmpl +``` + +其中 `{操作类型}` 是 `issue` 或 `pull`(针对合并请求),`{操作名称}` 是上述列出的操作名称之一。 + +例如,有关合并请求中的评论的电子邮件的特定模板是: + +```sh +custom/templates/mail/pull/comment.tmpl +``` + +然而,并不需要为每个操作类型/名称组合创建模板。 +使用回退系统来选择适当的模板。在此列表中,将使用 _第一个存在的_ 模板: + +- 所需**操作类型**和**操作名称**的特定模板。 +- 操作类型为 `issue` 和所需**操作名称**的模板。 +- 所需**操作类型**和操作名称为 `default` 的模板。 +- 操作类型为` issue` 和操作名称为 `default` 的模板。 + +唯一必需的模板是操作类型为 `issue` 操作名称为 `default` 的模板,除非用户在 `custom` 目录中覆盖了它。 + +## 模板语法 + +邮件模板是 UTF-8 编码的文本文件,需要遵循以下格式之一: + +``` +用于主题行的文本和宏 +------------ +用于邮件正文的文本和宏 +``` + +或者 + +``` +用于邮件正文的文本和宏 +``` + +指定 _主题_ 部分是可选的(因此也是虚线分隔符)。在使用时,_主题_ 和 _邮件正文_ 模板之间的分隔符需要至少三个虚线;分隔符行中不允许使用其他字符。 + +_主题_ 和 _邮件正文_ 由 [Golang的模板引擎](https://golang.org/pkg/text/template/) 解析,并提供了为每个通知组装的 _元数据上下文_。上下文包含以下元素: + +| 名称 | 类型 | 可用性 | 用途 | +| -------------------- | ------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `.FallbackSubject` | string | 始终可用 | 默认主题行。参见下文。 | +| `.Subject` | string | 仅在正文中可用 | 解析后的 _主题_。 | +| `.Body` | string | 始终可用 | 工单、合并请求或评论的消息,从 Markdown 解析为 HTML 并进行了清理。请勿与 _邮件正文_ 混淆。 | +| `.Link` | string | 始终可用 | 源工单、合并请求或评论的地址。 | +| `.Issue` | models.Issue | 始终可用 | 产生通知的工单(或合并请求)。要获取特定于合并请求的数据(例如 `HasMerged`),可以使用 `.Issue.PullRequest`,但需要注意,如果工单 _不是_ 合并请求,则该字段将为 `nil`。 | +| `.Comment` | models.Comment | 如果适用 | 如果通知是针对添加到工单或合并请求的评论,则其中包含有关评论的信息。 | +| `.IsPull` | bool | 始终可用 | 如果邮件通知与合并请求关联(即 `.Issue.PullRequest` 不为 `nil` ),则为 `true`。 | +| `.Repo` | string | 始终可用 | 仓库的名称,包括所有者名称(例如 `mike/stuff`) | +| `.User` | models.User | 始终可用 | 事件来源仓库的所有者。要获取用户名(例如 `mike`),可以使用 `.User.Name`。 | +| `.Doer` | models.User | 始终可用 | 执行触发通知事件的操作的用户。要获取用户名(例如 `rhonda`),可以使用 `.Doer.Name`。 | +| `.IsMention` | bool | 始终可用 | 如果此通知仅是因为在评论中提到了用户而生成的,并且收件人未订阅源,则为 `true`。如果收件人已订阅工单或仓库,则为 `false`。 | +| `.SubjectPrefix` | string | 始终可用 | 如果通知是关于除工单或合并请求创建之外的其他内容,则为 `Re:`;否则为空字符串。 | +| `.ActionType` | string | 始终可用 | `"issue"` 或 `"pull"`。它将与实际的 _操作类型_ 对应,与选择的模板无关。 | +| `.ActionName` | string | 始终可用 | 它将是上述操作类型之一(`new` ,`comment` 等),并与选择的模板对应。 | +| `.ReviewComments` | []models.Comment | 始终可用 | 审查中的代码评论列表。评论文本将在 `.RenderedContent` 中,引用的代码将在 `.Patch` 中。 | + +所有名称区分大小写。 + +### 模板中的主题部分 + +用于邮件主题的模板引擎是 Golang 的 [`text/template`](https://golang.org/pkg/text/template/)。 +有关语法的详细信息,请参阅链接的文档。 + +主题构建的步骤如下: + +- 根据通知类型和可用的模板选择一个模板。 +- 解析并解析模板(例如,将 `{{.Issue.Index}}` 转换为工单或合并请求的编号)。 +- 将所有空格字符(例如 `TAB`,`LF` 等)转换为普通空格。 +- 删除所有前导、尾随和多余的空格。 +- 将字符串截断为前 256 个字母(字符)。 + +如果最终结果为空字符串,**或者**没有可用的主题模板(即所选模板不包含主题部分),将使用Gitea的**内部默认值**。 + +内部默认(回退)主题相当于: + +``` +{{.SubjectPrefix}}[{{.Repo}}] {{.Issue.Title}} (#{{.Issue.Index}}) +``` + +例如:`Re: [mike/stuff] New color palette (#38)` + +即使存在有效的主题模板,Gitea的默认主题也可以在模板的元数据中作为 `.FallbackSubject` 找到。 + +### 模板中的邮件正文部分 + +用于邮件正文的模板引擎是 Golang 的 [`html/template`](https://golang.org/pkg/html/template/)。 +有关语法的详细信息,请参阅链接的文档。 + +邮件正文在邮件主题之后进行解析,因此还有一个额外的 _元数据_ 字段,即在考虑所有情况之后实际呈现的主题。 + +期望的结果是 HTML(包括结构元素,如``,``等)。可以通过 `