diff options
Diffstat (limited to 'docs/content/installation')
26 files changed, 0 insertions, 4590 deletions
diff --git a/docs/content/installation/_index.en-us.md b/docs/content/installation/_index.en-us.md deleted file mode 100644 index e69de29bb2..0000000000 --- a/docs/content/installation/_index.en-us.md +++ /dev/null diff --git a/docs/content/installation/_index.zh-cn.md b/docs/content/installation/_index.zh-cn.md deleted file mode 100644 index e69de29bb2..0000000000 --- a/docs/content/installation/_index.zh-cn.md +++ /dev/null diff --git a/docs/content/installation/comparison.en-us.md b/docs/content/installation/comparison.en-us.md deleted file mode 100644 index fdb8c3bcde..0000000000 --- a/docs/content/installation/comparison.en-us.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -date: "2018-05-07T13:00:00+02:00" -title: "Compared to other Git hosting" -slug: "comparison" -sidebar_position: 5 -toc: false -draft: false -aliases: - - /en-us/comparison -menu: - sidebar: - name: "Comparison" - sidebar_position: 5 - parent: installation - identifier: "comparison" ---- - -# Gitea compared to other Git hosting options - -To help decide if Gitea is suited for your needs, here is how it compares to other Git self hosted options. - -Be warned that we don't regularly check for feature changes in other products, so this list may be outdated. If you find anything that needs to be updated in the table below, please [open an issue](https://github.com/go-gitea/gitea/issues/new/choose). - -_Symbols used in table:_ - -- _✓ - supported_ - -- _⁄ - supported with limited functionality_ - -- _✘ - unsupported_ - -- _⚙️ - supported through third-party software_ - -## General Features - -| Feature | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | RhodeCode EE | -| ------------------------------------------------ | --------------------------------------------------- | ---- | --------- | --------- | --------- | --------- | ------------ | ------------ | -| Open source and free | ✓ | ✓ | ✘ | ✓ | ✘ | ✘ | ✓ | ✓ | -| Low RAM/ CPU usage | ✓ | ✓ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | -| Multiple database support | ✓ | ✓ | ✘ | ⁄ | ⁄ | ✓ | ✓ | ✓ | -| Multiple OS support | ✓ | ✓ | ✘ | ✘ | ✘ | ✘ | ✓ | ✓ | -| Easy upgrades | ✓ | ✓ | ✘ | ✓ | ✓ | ✘ | ✓ | ✓ | -| Telemetry | **✘** | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Third-party render tool support | ✓ | ✘ | ✘ | ✘ | ✘ | ✓ | ✘ | ✘ | -| WebAuthn (2FA) | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | ✓ | -| Extensive API | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Built-in Package/Container Registry | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ | -| Sync commits to an external repo (push mirror) | ✓ | ✓ | ✘ | ✓ | ✓ | ✘ | ✓ | ✓ | -| Sync commits from an external repo (pull mirror) | ✓ | ✘ | ✘ | ✓ | ✓ | ✘ | ✓ | ✓ | -| Light and Dark Theme | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ | -| Custom Theme Support | ✓ | ✓ | ✘ | ✘ | ✘ | ✓ | ✓ | ✓ | -| Markdown support | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| CSV support | ✓ | ✘ | ✓ | ✘ | ✘ | ✓ | ✘ | ✘ | -| 'GitHub / GitLab pages' | [⚙️][gitea-pages-server], [⚙️][gitea-caddy-plugin] | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ | -| Gists / Snippets | [⚙️][opengist] | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Repo-specific wiki (as a repo itself) | ✓ | ✓ | ✓ | ✓ | ✓ | / | ✘ | ✘ | -| Deploy Tokens | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Repository Tokens with write rights | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| RSS Feeds | ✓ | ✘ | ✓ | ✘ | ✘ | ✘ | ✓ | ✓ | -| Built-in CI/CD | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ | -| Subgroups: groups within groups | [✘](https://github.com/go-gitea/gitea/issues/1872) | ✘ | ✘ | ✓ | ✓ | ✘ | ✓ | ✓ | -| Interaction with other instances | [/](https://github.com/go-gitea/gitea/issues/18240) | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | -| Mermaid diagrams in Markdown | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ | -| Math syntax in Markdown | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✓ | ✓ | - -## Code management - -| Feature | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | RhodeCode EE | -| ------------------------------------------- | --------------------------------------------------- | ---- | --------- | --------- | --------- | --------- | ------------ | ------------ | -| Repository topics | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ | -| Repository code search | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Global code search | ✓ | ✘ | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | -| Git LFS 2.0 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Group Milestones | [✘](https://github.com/go-gitea/gitea/issues/14622) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | ✘ | -| Granular user roles (Code, Issues, Wiki, …) | ✓ | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | ✘ | -| Verified Committer | ⁄ | ✘ | ? | ✓ | ✓ | ✓ | ✘ | ✘ | -| GPG Signed Commits | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| SSH Signed Commits | ✓ | ✘ | ✓ | ✓ | ✓ | ? | ✘ | ✘ | -| Reject unsigned commits | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Migrating repos from other services | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Repository Activity page | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Branch manager | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Create new branches | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ | -| Web code editor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Commit graph | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Template Repositories | ✓ | ✘ | ✓ | ✘ | ✓ | ✓ | ✘ | ✘ | -| Git Blame | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Visual comparison of image changes | ✓ | ✘ | ✓ | ? | ? | ? | ✘ | ✘ | - -- Gitea has builtin repository-level code search -- Better code search support could be achieved by [using a repository indexer](administration/repo-indexer.md) - -## Issue Tracker - -| Feature | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | RhodeCode EE | -| ----------------------------- | --------------------------------------------------- | ---- | --------- | --------- | --------- | --------- | ------------ | ------------ | -| Issue tracker | ✓ | ✓ | ✓ | ✓ | ✓ | / | ✘ | ✘ | -| Issue templates | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ | -| Labels | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ | -| Time tracking | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ | -| Multiple assignees for issues | ✓ | ✘ | ✓ | ✘ | ✓ | ✘ | ✘ | ✘ | -| Related issues | ✘ | ✘ | ⁄ | ✓ | ✓ | ✘ | ✘ | ✘ | -| Confidential issues | [✘](https://github.com/go-gitea/gitea/issues/3217) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | ✘ | -| Comment reactions | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ | -| Lock Discussion | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ | -| Batch issue handling | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ | -| Projects | [/](https://github.com/go-gitea/gitea/issues/14710) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | ✘ | -| Create branch from issue | [✘](https://github.com/go-gitea/gitea/issues/20226) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | ✘ | -| Convert comment to new issue | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ | -| Issue search | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Global issue search | [/](https://github.com/go-gitea/gitea/issues/2434) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Issue dependency | ✓ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | -| Create issue via email | [✘](https://github.com/go-gitea/gitea/issues/6226) | ✘ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Service Desk | [✘](https://github.com/go-gitea/gitea/issues/6219) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | ✘ | - -## Pull/Merge requests - -| Feature | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | RhodeCode EE | -| ----------------------------------------------- | -------------------------------------------------- | ---- | --------- | --------- | --------- | --------- | ------------ | ------------ | -| Pull/Merge requests | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Squash merging | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Rebase merging | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Pull/Merge request inline comments | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Pull/Merge request approval | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Pull/Merge require approval | ✓ | ✘ | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | -| Pull/Merge multiple reviewers | ✓ | ✓ | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | -| Merge conflict resolution | [✘](https://github.com/go-gitea/gitea/issues/9014) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Restrict push and merge access to certain users | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Revert specific commits | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Pull/Merge requests templates | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | ✘ | -| Cherry-picking changes | ✓ | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | ✓ | -| Download Patch | ✓ | ✘ | ✓ | ✓ | ✓ | / | ✓ | ✓ | -| Merge queues | ✘ | ✘ | ✓ | ✘ | ✓ | ✘ | ✘ | ✘ | - -## 3rd-party integrations - -| Feature | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | RhodeCode EE | -| ---------------------------------------------- | ------------------------------------------------ | ---- | --------- | --------- | --------- | --------- | ------------ | ------------ | -| Webhooks | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Git Hooks | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| AD / LDAP integration | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Multiple LDAP / AD server support | ✓ | ✓ | ✘ | ✘ | ✓ | ✓ | ✓ | ✓ | -| LDAP user synchronization | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | ✓ | -| SAML 2.0 service provider | [✘](https://github.com/go-gitea/gitea/issues/5512) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | ✓ | -| OpenID Connect support | ✓ | ✘ | ✓ | ✓ | ✓ | ? | ✘ | ✓ | -| OAuth 2.0 integration (external authorization) | ✓ | ✘ | ⁄ | ✓ | ✓ | ? | ✘ | ✓ | -| Act as OAuth 2.0 provider | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Two factor authentication (2FA) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✓ | -| Integration with the most common services | ✓ | / | ⁄ | ✓ | ✓ | ⁄ | ✓ | ✓ | -| Incorporate external CI/CD | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - -[gitea-caddy-plugin]: https://github.com/42wim/caddy-gitea -[gitea-pages-server]: https://codeberg.org/Codeberg/pages-server -[opengist]: https://github.com/thomiceli/opengist diff --git a/docs/content/installation/comparison.zh-cn.md b/docs/content/installation/comparison.zh-cn.md deleted file mode 100644 index 422d6314c5..0000000000 --- a/docs/content/installation/comparison.zh-cn.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -date: "2019-02-14T11:51:04+08:00" -title: "对比 Gitea 与其它 Git 托管工具" -slug: "comparison" -sidebar_position: 5 -toc: false -draft: false -aliases: - - /zh-cn/comparison -menu: - sidebar: - parent: "installation" - name: "横向对比" - sidebar_position: 5 - identifier: "comparison" ---- - -# 对比 Gitea 与其它 Git 托管工具 - -这里列出了 Gitea 与其它一些 Git 托管工具之间的异同，以便确认 Gitea 是否能够满足您的需求。 - -请注意，此列表中的某些表项可能已经过时，因为我们并没有定期检查其它产品的功能是否有所更改。你可以前往 [Github issue](https://github.com/go-gitea/gitea/issues) 来帮助我们更新过时的内容，感谢！ - -_表格中的符号含义:_ - -* _✓ - 支持_ - -* _⁄ - 部分支持_ - -* _✘ - 不支持_ - -* _⚙️ - 由第三方服务或插件支持_ - -#### 主要特性 - -| 特性 | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | -| ------------------------------- | -------------------------------------------------- | ---- | --------- | --------- | --------- | -------------- | ------------ | -| 开源免费 | ✓ | ✓ | ✘ | ✓ | ✘ | ✘ | ✓ | -| 低资源开销 (RAM/CPU) | ✓ | ✓ | ✘ | ✘ | ✘ | ✘ | ✘ | -| 支持多种数据库 | ✓ | ✓ | ✘ | ⁄ | ⁄ | ✓ | ✓ | -| 支持多种操作系统 | ✓ | ✓ | ✘ | ✘ | ✘ | ✘ | ✓ | -| 升级简便 | ✓ | ✓ | ✘ | ✓ | ✓ | ✘ | ✓ | -| 可观测性 | **✘** | ✘ | ✓ | ✓ | ✓ | ✓ | ? | -| 支持第三方渲染工具 | ✓ | ✘ | ✘ | ✘ | ✘ | ✓ | ? | -| WebAuthn (2FA) | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ? | -| 扩展 API | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| 内置软件包/容器注册中心 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | -| 同步提交到外部仓库 (push mirror) | ✓ | ✓ | ✘ | ✓ | ✓ | ✘ | ✓ | -| 同步外部仓库的提交 (pull mirror) | ✓ | ✘ | ✘ | ✓ | ✓ | ✘ | ? | -| 浅色和深色主题 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ? | -| 自定义主题支持 | ✓ | ✓ | ✘ | ✘ | ✘ | ✓ | ✘ | -| 支持 Markdown | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| 支持 CSV | ✓ | ✘ | ✓ | ✘ | ✘ | ✓ | ? | -| Git 驱动的静态 pages | [⚙️][gitea-pages-server], [⚙️][gitea-caddy-plugin] | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Git 驱动的集成化 wiki | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ (cloud only) | ✘ | -| 部署令牌 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| 仓库写权限令牌 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | -| RSS Feeds | ✓ | ✘ | ✓ | ✘ | ✘ | ✘ | ✘ | -| 内置 CI/CD | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | -| 子组织：组织内的组织 | [✘](https://github.com/go-gitea/gitea/issues/1872) | ✘ | ✘ | ✓ | ✓ | ✘ | ✓ | -| 多实例交互 | [/](https://github.com/go-gitea/gitea/issues/18240) | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | -| Markdown绘图 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Markdown数学公式 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | - -#### 代码管理 - -| 特性 | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | -| ------------------------------------ | --------------------------------------------------- | ---- | --------- | --------- | --------- | --------- | ------------ | -| 仓库主题描述 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | -| 仓库内代码搜索 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | -| 全局代码搜索 | ✓ | ✘ | ✓ | ✘ | ✓ | ✓ | ✓ | -| Git LFS 2.0 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | -| 组织里程碑 | [✘](https://github.com/go-gitea/gitea/issues/14622) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | -| 细粒度用户角色 | ✓ | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | -| 提交人的身份验证 | ⁄ | ✘ | ? | ✓ | ✓ | ✓ | ✘ | -| GPG 签名的提交 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | -| SSH 签名的提交 | ✓ | ✘ | ✓ | ✓ | ✓ | ? | ? | -| 拒绝未通过验证的提交 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | -| 外部仓库迁移 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | -| 仓库活跃度页面 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | -| 分支管理 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | -| 建立新分支 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | -| 在线代码编辑 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| 提交的统计图表 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | -| 模板仓库 | ✓ | ✘ | ✓ | ✘ | ✓ | ✓ | ✘ | -| Git Blame | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | -| 可视化镜像变化 | ✓ | ✘ | ✓ | ? | ? | ? | ? | - -#### 工单管理 - -| 特性 | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | -| ------------------- | -------------------------------------------------- | --------------------------------------------- | --------- | ----------------------------------------------------------------------- | --------- | -------------- | ------------ | -| 工单跟踪 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ (cloud only) | ✘ | -| 工单模板 | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | -| 标签 | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | -| 时间跟踪 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | -| 支持多个负责人 | ✓ | ✘ | ✓ | ✘ | ✓ | ✘ | ✘ | -| 关联的工单 | ✘ | ✘ | ⁄ | [✓](https://docs.gitlab.com/ce/user/project/issues/related_issues.html) | ✓ | ✘ | ✘ | -| 私密工单 | [✘](https://github.com/go-gitea/gitea/issues/3217) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | -| 评论反馈 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | -| 锁定讨论 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | -| 工单批处理 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | -| 工单看板 | [✓](https://github.com/go-gitea/gitea/pull/8346) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | -| 从工单创建分支 | ✘ | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | -| 从评论创建工单 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | -| 工单搜索 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | -| 工单全局搜索 | [✘](https://github.com/go-gitea/gitea/issues/2434) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | -| 工单依赖关系 | ✓ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | -| 通过 Email 创建工单 | [✘](https://github.com/go-gitea/gitea/issues/6226) | [✘](https://github.com/gogs/gogs/issues/2602) | ✘ | ✓ | ✓ | ✓ | ✘ | -| 服务台 | [✘](https://github.com/go-gitea/gitea/issues/6219) | ✘ | ✘ | [✓](https://gitlab.com/groups/gitlab-org/-/epics/3103) | ✓ | ✘ | ✘ | - -#### Pull/Merge requests - -| 特性 | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | -| ------------------------------------ | -------------------------------------------------- | ---- | --------- | --------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------ | ------------ | -| Pull/Merge requests | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Squash merging | ✓ | ✘ | ✓ | [✓](https://docs.gitlab.com/ce/user/project/merge_requests/squash_and_merge.html) | ✓ | ✓ | ✓ | -| Rebase merging | ✓ | ✓ | ✓ | ✘ | ⁄ | ✘ | ✓ | -| 评论 Pull/Merge request 中的某行代码 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | -| 指定 Pull/Merge request 的审核人 | ✓ | ✘ | ⁄ | ✓ | ✓ | ✓ | ✓ | -| 解决 Merge 冲突 | [✘](https://github.com/go-gitea/gitea/issues/5158) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | -| 限制某些用户的 push 和 merge 权限 | ✓ | ✘ | ✓ | ⁄ | ✓ | ✓ | ✓ | -| 回退某些 commits 或 merge request | [✓](https://github.com/go-gitea/gitea/issues/5158) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | -| Pull/Merge requests 模板 | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | -| 查看 Cherry-picking 的更改 | [✓](https://github.com/go-gitea/gitea/issues/5158) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | -| 下载 Patch | ✓ | ✘ | ✓ | ✓ | ✓ | [/](https://jira.atlassian.com/plugins/servlet/mobile#issue/BCLOUD-8323) | ✘ | -| Merge queues | ✘ | ✘ | ✓ | ✘ | ✓ | ✘ | ✘ | - -#### 第三方集成 - -| 特性 | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | -| -------------------------- | -------------------------------------------------- | --------------------------------------------- | --------- | --------- | --------- | --------- | ------------ | -| 支持 Webhook | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| 自定义 Git 钩子 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| 集成 AD / LDAP | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| 支持多个 LDAP / AD 服务 | ✓ | ✓ | ✘ | ✘ | ✓ | ✓ | ✓ | -| LDAP 用户同步 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | -| SAML 2.0 service provider | [✘](https://github.com/go-gitea/gitea/issues/5512) | [✘](https://github.com/gogs/gogs/issues/1221) | ✓ | ✓ | ✓ | ✓ | ✘ | -| 支持 OpenId 连接 | ✓ | ✘ | ✓ | ✓ | ✓ | ? | ✘ | -| 集成 OAuth 2.0（外部授权） | ✓ | ✘ | ⁄ | ✓ | ✓ | ? | ✓ | -| 作为 OAuth 2.0 provider | [✓](https://github.com/go-gitea/gitea/pull/5378) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | -| 二次验证 (2FA) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | -| 集成 Mattermost/Slack | ✓ | ✓ | ⁄ | ✓ | ✓ | ⁄ | ✓ | -| 集成 Discord | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ | -| 集成 Microsoft Teams | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ | -| 显示外部 CI/CD 的状态 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | - -[gitea-caddy-plugin]: https://github.com/42wim/caddy-gitea -[gitea-pages-server]: https://codeberg.org/Codeberg/pages-server diff --git a/docs/content/installation/database-preparation.en-us.md b/docs/content/installation/database-preparation.en-us.md deleted file mode 100644 index e6abb8a613..0000000000 --- a/docs/content/installation/database-preparation.en-us.md +++ /dev/null @@ -1,309 +0,0 @@ ---- -date: "2020-01-16" -title: "Database Preparation" -slug: "database-prep" -sidebar_position: 10 -toc: false -draft: false -aliases: - - /en-us/database-prep -menu: - sidebar: - parent: "installation" - name: "Database preparation" - sidebar_position: 10 - identifier: "database-prep" ---- - -# Database Preparation - -You need a database to use Gitea. Gitea supports PostgreSQL (>= 12), MySQL (>= 8.0), MariaDB (>= 10.4), SQLite (builtin), and MSSQL (>= 2012 SP4). This page will guide into preparing database. Only PostgreSQL and MySQL will be covered here since those database engines are widely-used in production. If you plan to use SQLite, you can ignore this chapter. - -If you use an unsupported database version, please [get in touch](/help/support) with us for information on our Extended Support Contracts. We can provide testing and support for older databases and integrate those fixes into the Gitea codebase. - -Database instance can be on same machine as Gitea (local database setup), or on different machine (remote database). - -Note: All steps below requires that the database engine of your choice is installed on your system. For remote database setup, install the server application on database instance and client program on your Gitea server. The client program is used to test connection to the database from Gitea server, while Gitea itself use database driver provided by Go to accomplish the same thing. In addition, make sure you use same engine version for both server and client for some engine features to work. For security reason, protect `root` (MySQL) or `postgres` (PostgreSQL) database superuser with secure password. The steps assumes that you run Linux for both database and Gitea servers. - -## MySQL/MariaDB - -1. For remote database setup, you will need to make MySQL listen to your IP address. Edit `bind-address` option on `/etc/mysql/my.cnf` on database instance to: - - ```ini - bind-address = 203.0.113.3 - ``` - -2. On database instance, login to database console as root: - - ``` - mysql -u root -p - ``` - - Enter the password as prompted. - -3. Create database user which will be used by Gitea, authenticated by password. This example uses `'gitea'` as password. Please use a secure password for your instance. - - For local database: - - ```sql - SET old_passwords=0; - CREATE USER 'gitea'@'%' IDENTIFIED BY 'gitea'; - ``` - - For remote database: - - ```sql - SET old_passwords=0; - CREATE USER 'gitea'@'192.0.2.10' IDENTIFIED BY 'gitea'; - ``` - - where `192.0.2.10` is the IP address of your Gitea instance. - - Replace username and password above as appropriate. - -4. Create database with UTF-8 charset and case-sensitive collation. - - `utf8mb4_bin` is a common collation for both MySQL/MariaDB. - When Gitea starts, it will try to find a better collation (`utf8mb4_0900_as_cs` or `uca1400_as_cs`) and alter the database if it is possible. - If you would like to use other collation, you can set `[database].CHARSET_COLLATION` in the `app.ini` file. - - ```sql - CREATE DATABASE giteadb CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_bin'; - ``` - - Replace database name as appropriate. - -5. Grant all privileges on the database to database user created above. - - For local database: - - ```sql - GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea'; - FLUSH PRIVILEGES; - ``` - - For remote database: - - ```sql - GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea'@'192.0.2.10'; - FLUSH PRIVILEGES; - ``` - -6. Quit from database console by `exit`. - -7. On your Gitea server, test connection to the database: - - ``` - mysql -u gitea -h 203.0.113.3 -p giteadb - ``` - - where `gitea` is database username, `giteadb` is database name, and `203.0.113.3` is IP address of database instance. Omit `-h` option for local database. - - You should be connected to the database. - -## PostgreSQL - -1. For remote database setup, configure PostgreSQL on database instance to listen to your IP address by editing `listen_addresses` on `postgresql.conf` to: - - ```ini - listen_addresses = 'localhost, 203.0.113.3' - ``` - -2. PostgreSQL uses `md5` challenge-response encryption scheme for password authentication by default. Nowadays this scheme is not considered secure anymore. Use SCRAM-SHA-256 scheme instead by editing the `postgresql.conf` configuration file on the database server to: - - ```ini - password_encryption = scram-sha-256 - ``` - - Restart PostgreSQL to apply the setting. - -3. On the database server, login to the database console as superuser: - - ``` - su -c "psql" - postgres - ``` - -4. Create database user (role in PostgreSQL terms) with login privilege and password. Please use a secure, strong password instead of `'gitea'` below: - - ```sql - CREATE ROLE gitea WITH LOGIN PASSWORD 'gitea'; - ``` - - Replace username and password as appropriate. - -5. Create database with UTF-8 charset and owned by the database user created earlier. Any `libc` collations can be specified with `LC_COLLATE` and `LC_CTYPE` parameter, depending on expected content: - - ```sql - CREATE DATABASE giteadb WITH OWNER gitea TEMPLATE template0 ENCODING UTF8 LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8'; - ``` - - Replace database name as appropriate. - -6. Allow the database user to access the database created above by adding the following authentication rule to `pg_hba.conf`. - - For local database: - - ```ini - local giteadb gitea scram-sha-256 - ``` - - For remote database: - - ```ini - host giteadb gitea 192.0.2.10/32 scram-sha-256 - ``` - - Replace database name, user, and IP address of Gitea instance with your own. - - Note: rules on `pg_hba.conf` are evaluated sequentially, that is the first matching rule will be used for authentication. Your PostgreSQL installation may come with generic authentication rules that match all users and databases. You may need to place the rules presented here above such generic rules if it is the case. - - Restart PostgreSQL to apply new authentication rules. - -7. On your Gitea server, test connection to the database. - - For local database: - - ``` - psql -U gitea -d giteadb - ``` - - For remote database: - - ``` - psql "postgres://gitea@203.0.113.3/giteadb" - ``` - - where `gitea` is database user, `giteadb` is database name, and `203.0.113.3` is IP address of your database instance. - - You should be prompted to enter password for the database user, and connected to the database. - -## Database Connection over TLS - -If the communication between Gitea and your database instance is performed through a private network, or if Gitea and the database are running on the same server, this section can be omitted since the security between Gitea and the database instance is not critically exposed. If instead the database instance is on a public network, use TLS to encrypt the connection to the database, as it is possible for third-parties to intercept the traffic data. - -### Prerequisites - -- You need two valid TLS certificates, one for the database instance (database server) and one for the Gitea instance (database client). Both certificates must be signed by a trusted CA. -- The database certificate must contain `TLS Web Server Authentication` in the `X509v3 Extended Key Usage` extension attribute, while the client certificate needs `TLS Web Client Authentication` in the corresponding attribute. -- On the database server certificate, one of `Subject Alternative Name` or `Common Name` entries must be the fully-qualified domain name (FQDN) of the database instance (e.g. `db.example.com`). On the database client certificate, one of the entries mentioned above must contain the database username that Gitea will be using to connect. -- You need domain name mappings of both Gitea and database servers to their respective IP addresses. Either set up DNS records for them or add local mappings to `/etc/hosts` (`%WINDIR%\System32\drivers\etc\hosts` in Windows) on each system. This allows the database connections to be performed by domain name instead of IP address. See documentation of your system for details. - -### PostgreSQL TLS - -The PostgreSQL driver used by Gitea supports two-way TLS. In two-way TLS, both database client and server authenticate each other by sending their respective certificates to their respective opposite for validation. In other words, the server verifies client certificate, and the client verifies server certificate. - -1. On the server with the database instance, place the following credentials: - - - `/path/to/postgresql.crt`: Database instance certificate - - `/path/to/postgresql.key`: Database instance private key - - `/path/to/root.crt`: CA certificate chain to validate client certificates - -2. Add following options to `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. Adjust credentials ownership and permission, as required by 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. Edit `pg_hba.conf` rule to only allow Gitea database user to connect over SSL, and to require client certificate verification. - - For PostgreSQL 12: - - ```ini - hostssl giteadb gitea 192.0.2.10/32 scram-sha-256 clientcert=verify-full - ``` - - For PostgreSQL 11 and earlier: - - ```ini - hostssl giteadb gitea 192.0.2.10/32 scram-sha-256 clientcert=1 - ``` - - Replace database name, user, and IP address of Gitea instance as appropriate. - -5. Restart PostgreSQL to apply configurations above. - -6. On the server running the Gitea instance, place the following credentials under the home directory of the user who runs Gitea (e.g. `git`): - - - `~/.postgresql/postgresql.crt`: Database client certificate - - `~/.postgresql/postgresql.key`: Database client private key - - `~/.postgresql/root.crt`: CA certificate chain to validate server certificate - - Note: Those file names above are hardcoded in PostgreSQL and it is not possible to change them. - -7. Adjust credentials, ownership and permission as required: - - ``` - chown git:git ~/.postgresql/postgresql.crt ~/.postgresql/postgresql.key ~/.postgresql/root.crt - chown 0600 ~/.postgresql/postgresql.crt ~/.postgresql/postgresql.key ~/.postgresql/root.crt - ``` - -8. Test the connection to the database: - - ``` - psql "postgres://gitea@example.db/giteadb?sslmode=verify-full" - ``` - - You should be prompted to enter password for the database user, and then be connected to the database. - -### MySQL/MariaDB TLS - -While the MySQL driver used by Gitea also supports two-way TLS, Gitea currently supports only one-way TLS. See issue #10828 for details. - -In one-way TLS, the database client verifies the certificate sent from server during the connection handshake, and the server assumes that the connected client is legitimate, since client certificate verification doesn't take place. - -1. On the database instance, place the following credentials: - - - `/path/to/mysql.crt`: Database instance certificate - - `/path/to/mysql.key`: Database instance key - - `/path/to/ca.crt`: CA certificate chain. This file isn't used on one-way TLS, but is used to validate client certificates on two-way TLS. - -2. Add following options to `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. Adjust credentials ownership and permission: - - ``` - 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. Restart MySQL to apply the setting. - -5. The database user for Gitea may have been created earlier, but it would authenticate only against the IP addresses of the server running Gitea. To authenticate against its domain name, recreate the user, and this time also set it to require TLS for connecting to the database: - - ```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; - ``` - - Replace database user name, password, and Gitea instance domain as appropriate. - -6. Make sure that the CA certificate chain required to validate the database server certificate is on the system certificate store of both the database and Gitea servers. Consult your system documentation for instructions on adding a CA certificate to the certificate store. - -7. On the server running Gitea, test connection to the database: - - ``` - mysql -u gitea -h example.db -p --ssl - ``` - - You should be connected to the database. diff --git a/docs/content/installation/database-preparation.zh-cn.md b/docs/content/installation/database-preparation.zh-cn.md deleted file mode 100644 index 3fde004a8c..0000000000 --- a/docs/content/installation/database-preparation.zh-cn.md +++ /dev/null @@ -1,309 +0,0 @@ ---- -date: "2020-01-16" -title: "数据库准备" -slug: "database-prep" -sidebar_position: 10 -toc: false -draft: false -aliases: - - /zh-cn/database-prep -menu: - sidebar: - parent: "installation" - name: "数据库准备" - sidebar_position: 10 - identifier: "database-prep" ---- - -# 数据库准备 - -在使用 Gitea 前，您需要准备一个数据库。Gitea 支持 PostgreSQL（>= 12）、MySQL（>= 8.0）、MariaDB（>= 10.4）、SQLite（内置） 和 MSSQL（>= 2012 SP4）这几种数据库。本页将指导您准备数据库。由于 PostgreSQL 和 MySQL 在生产环境中被广泛使用，因此本文档将仅涵盖这两种数据库。如果您计划使用 SQLite，则可以忽略本章内容。 - -如果您使用不受支持的数据库版本，请通过 [联系我们](/help/support) 以获取有关我们的扩展支持的信息。我们可以为旧数据库提供测试和支持，并将这些修复集成到 Gitea 代码库中。 - -数据库实例可以与 Gitea 实例在相同机器上（本地数据库），也可以与 Gitea 实例在不同机器上（远程数据库）。 - -注意：以下所有步骤要求您的选择的数据库引擎已安装在您的系统上。对于远程数据库设置，请在数据库实例上安装服务器应用程序，在 Gitea 服务器上安装客户端程序。客户端程序用于测试 Gitea 服务器与数据库之间的连接，而 Gitea 本身使用 Go 提供的数据库驱动程序完成相同的任务。此外，请确保服务器和客户端使用相同的引擎版本，以使某些引擎功能正常工作。出于安全原因，请使用安全密码保护 `root`（MySQL）或 `postgres`（PostgreSQL）数据库超级用户。以下步骤假设您在数据库和 Gitea 服务器上都使用 Linux。 - -## MySQL/MariaDB - -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_bin` 是 MySQL/MariaDB 的通用排序规则。 - Gitea 启动后会尝试把数据库修改为更合适的字符集 (`utf8mb4_0900_as_cs` 或者 `uca1400_as_cs`) 并在可能的情况下更改数据库。 - 如果你想指定自己的字符集规则，可以在 `app.ini` 中设置 `[database].CHARSET_COLLATION`。 - - ```sql - CREATE DATABASE giteadb CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_bin'; - ``` - - 根据需要替换数据库名称。 - -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 TLS - -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/MariaDB TLS - -虽然 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 - ``` - - 至此应该成功连接到数据库了。 diff --git a/docs/content/installation/from-binary.en-us.md b/docs/content/installation/from-binary.en-us.md deleted file mode 100644 index 88f82be322..0000000000 --- a/docs/content/installation/from-binary.en-us.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -date: "2017-06-19T12:00:00+02:00" -title: "Installation from binary" -slug: "install-from-binary" -sidebar_position: 15 -toc: false -draft: false -aliases: - - /en-us/install-from-binary -menu: - sidebar: - parent: "installation" - name: "From binary" - sidebar_position: 15 - identifier: "install-from-binary" ---- - -# Installation from binary - -All downloads come with SQLite, MySQL and PostgreSQL support, and are built with -embedded assets. This can be different from Gogs. - -## Download - -You can find the file matching your platform from the [downloads page](https://dl.gitea.com/gitea/) after navigating to the version you want to download. - -### Choosing the right file - -**For Linux**, you will likely want `linux-amd64`. It's for 64-bit Intel/AMD platforms, but there are other platforms available, including `arm64` (e.g. Raspberry PI 4), `386` (i.e. 32-bit), `arm-5`, and `arm-6`. - -**For Windows**, you will likely want `windows-4.0-amd64`. It's for all modern versions of Windows, but there is also a `386` platform available designed for older, 32-bit versions of Windows. - -*Note: there is also a `gogit-windows` file available that was created to help with some [performance problems](https://github.com/go-gitea/gitea/pull/15482) reported by some Windows users on older systems/versions. You should consider using this file if you're experiencing performance issues, and let us know if it improves performance.* - -**For macOS**, you should choose `darwin-arm64` if your hardware uses Apple Silicon, or `darwin-amd64` for Intel. - -**For FreeBSD**, you should choose `freebsd12-amd64` for 64-bit Intel/AMD platforms. - -### Downloading with wget - -Copy the commands below and replace the URL within the one you wish to download. - -```sh -wget -O gitea https://dl.gitea.com/gitea/@version@/gitea-@version@-linux-amd64 -chmod +x gitea -``` - -Note that the above command will download Gitea @version@ for 64-bit Linux. - -## Verify GPG signature - -Gitea signs all binaries with a [GPG key](https://keys.openpgp.org/search?q=teabot%40gitea.io) to prevent against unwanted modification of binaries. -To validate the binary, download the signature file which ends in `.asc` for the binary you downloaded and use the GPG command line tool. - -```sh -gpg --keyserver keys.openpgp.org --recv 7C9E68152594688862D62AF62D9AE806EC1592E2 -gpg --verify gitea-@version@-linux-amd64.asc gitea-@version@-linux-amd64 -``` - -Look for the text `Good signature from "Teabot <teabot@gitea.io>"` to assert a good binary, -despite warnings like `This key is not certified with a trusted signature!`. - -## Recommended server configuration - -**NOTE:** Many of the following directories can be configured using [Environment Variables](administration/environment-variables.md) as well! -Of note, configuring `GITEA_WORK_DIR` will tell Gitea where to base its working directory, as well as ease installation. - -### Prepare environment - -Check that Git is installed on the server. If it is not, install it first. Gitea requires Git version >= 2.0. - -```sh -git --version -``` - -Create a user to run Gitea (e.g. `git`) - -```sh -# On Ubuntu/Debian: -adduser \ - --system \ - --shell /bin/bash \ - --gecos 'Git Version Control' \ - --group \ - --disabled-password \ - --home /home/git \ - git - -# On Fedora/RHEL/CentOS: -groupadd --system git -adduser \ - --system \ - --shell /bin/bash \ - --comment 'Git Version Control' \ - --gid git \ - --home-dir /home/git \ - --create-home \ - git -``` - -### Create required directory structure - -```sh -mkdir -p /var/lib/gitea/{custom,data,log} -chown -R git:git /var/lib/gitea/ -chmod -R 750 /var/lib/gitea/ -mkdir /etc/gitea -chown root:git /etc/gitea -chmod 770 /etc/gitea -``` - -> **NOTE:** `/etc/gitea` is temporarily set with write permissions for user `git` so that the web installer can write the configuration file. After the installation is finished, it is recommended to set permissions to read-only using: -> -> ```sh -> chmod 750 /etc/gitea -> chmod 640 /etc/gitea/app.ini -> ``` - -If you don't want the web installer to be able to write to the config file, it is possible to make the config file read-only for the Gitea user (owner/group `root:git`, mode `0640`) however you will need to edit your config file manually to: - -* Set `INSTALL_LOCK= true`, -* Ensure all database configuration details are set correctly -* Ensure that the `SECRET_KEY` and `INTERNAL_TOKEN` values are set. (You may want to use the `gitea generate secret` to generate these secret keys.) -* Ensure that any other secret keys you need are set. - -See the [command line documentation](administration/command-line.md) for information on using `gitea generate secret`. - -### Configure Gitea's working directory - -**NOTE:** If you plan on running Gitea as a Linux service, you can skip this step, as the service file allows you to set `WorkingDirectory`. Otherwise, consider setting this environment variable (semi-)permanently so that Gitea consistently uses the correct working directory. - -```sh -export GITEA_WORK_DIR=/var/lib/gitea/ -``` - -### Copy the Gitea binary to a global location - -```sh -cp gitea /usr/local/bin/gitea -``` - -### Adding bash/zsh autocompletion (from 1.19) - -A script to enable bash-completion can be found at [`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete). This can be copied to `/usr/share/bash-completion/completions/gitea` -or sourced within your `.bashrc`. - -Similarly a script for zsh-completion can be found at [`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete). This can be copied to `/usr/share/zsh/_gitea` or sourced within your -`.zshrc`. - -YMMV and these scripts may need further improvement. - -## Running Gitea - -After you complete the above steps, you can run Gitea two ways: - -### 1. Creating a service file to start Gitea automatically (recommended) - -See how to create [Linux service](installation/run-as-service-in-ubuntu.md) - -### 2. Running from command-line/terminal - -```sh -GITEA_WORK_DIR=/var/lib/gitea/ /usr/local/bin/gitea web -c /etc/gitea/app.ini -``` - -## Updating to a new version - -You can update to a new version of Gitea by stopping Gitea, replacing the binary at `/usr/local/bin/gitea` and restarting the instance. -The binary file name should not be changed during the update to avoid problems in existing repositories. - -It is recommended that you make a [backup](administration/backup-and-restore.md) before updating your installation. - -If you have carried out the installation steps as described above, the binary should -have the generic name `gitea`. Do not change this, i.e. to include the version number. - -### 1. Restarting Gitea with systemd (recommended) - -As we explained before, we recommend to use systemd as the service manager. In this case, `systemctl restart gitea` should be fine. - -### 2. Restarting Gitea without systemd - -To restart your Gitea instance, we recommend to use SIGHUP signal. If you know your Gitea PID, use `kill -1 $GITEA_PID`, otherwise you can use `killall -1 gitea`. - -To gracefully stop the Gitea instance, a simple `kill $GITEA_PID` or `killall gitea` is enough. - -**NOTE:** We don't recommend to use the SIGKILL signal (`-9`); you may be forcefully stopping some of Gitea's internal tasks, and it will not gracefully stop (tasks in queues, indexers, etc.) - -See below for troubleshooting instructions to repair broken repositories after -an update of your Gitea version. - -## Troubleshooting - -### Old glibc versions - -Older Linux distributions (such as Debian 7 and CentOS 6) may not be able to load the -Gitea binary, usually producing an error such as `./gitea: /lib/x86_64-linux-gnu/libc.so.6: -version 'GLIBC\_2.14' not found (required by ./gitea)`. This is due to the integrated -SQLite support in the binaries provided by dl.gitea.com. In this situation, it is usually -possible to [install from source](installation/from-source.md), without including -SQLite support. - -### Running Gitea on another port - -For errors like `702 runWeb()] [E] Failed to start server: listen tcp 0.0.0.0:3000: -bind: address already in use`, Gitea needs to be started on another free port. This -is possible using `./gitea web -p $PORT`. It's possible another instance of Gitea -is already running. - -### Running Gitea on Raspbian - -As of v1.8, there is a problem with the arm7 version of Gitea, and it doesn't run on Raspberry Pis and similar devices. - -It is recommended to switch to the arm6 version, which has been tested and shown to work on Raspberry Pis and similar devices. - -<!--- -please remove after fixing the arm7 bug ----> -### Git error after updating to a new version of Gitea - -If during the update, the binary file name has been changed to a new version of Gitea, -Git Hooks in existing repositories will not work any more. In that case, a Git -error will be displayed when pushing to the repository. - -``` -remote: ./hooks/pre-receive.d/gitea: line 2: [...]: No such file or directory -``` - -The `[...]` part of the error message will contain the path to your previous Gitea -binary. - -To solve this, go to the admin options and run the task `Resynchronize pre-receive, -update and post-receive hooks of all repositories` to update all hooks to contain -the new binary path. Please note that this overwrites all Git Hooks, including ones -with customizations made. - -If you aren't using the Gitea built-in SSH server, you will also need to re-write -the authorized key file by running the `Update the '.ssh/authorized_keys' file with -Gitea SSH keys.` task in the admin options. diff --git a/docs/content/installation/from-binary.zh-cn.md b/docs/content/installation/from-binary.zh-cn.md deleted file mode 100644 index 216a6be51e..0000000000 --- a/docs/content/installation/from-binary.zh-cn.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -date: "2016-12-01T16:00:00+02:00" -title: "使用二进制文件安装" -slug: "install-from-binary" -sidebar_position: 15 -toc: false -draft: false -aliases: - - /zh-cn/install-from-binary -menu: - sidebar: - parent: "installation" - name: "使用二进制文件安装" - sidebar_position: 15 - identifier: "install-from-binary" ---- - -# 使用二进制文件安装 - -所有打包的二进制程序均包含 SQLite，MySQL 和 PostgreSQL 的数据库连接支持，同时网站的静态资源均已嵌入到可执行程序中，这一点和曾经的 Gogs 有所不同。 - -## 下载 - -你可以从 [下载页面](https://dl.gitea.com/gitea/) 选择对应平台的二进制文件。 - -### 选择架构 - -- **对于 Linux**，`linux-amd64` 适用于 64-bit 的 Intel/AMD 平台。更多架构包含 `arm64` (Raspberry PI 4)，`386` (32-bit)，`arm-5` 以及 `arm-6`。 - -- **对于 Windows**，`windows-4.0-amd64` 适用于 64-bit 的 Intel/AMD 平台，`386` 适用于 32-bit 的 Intel/AMD 平台。（提示：`gogit-windows` 版本内建了 gogit 可能缓解在旧的 Windows 平台上 Go 程序调用 git 子程序时面临的 [性能问题](https://github.com/go-gitea/gitea/pull/15482)） - -- **对于 macOS**，`darwin-arm64` 适用于 Apple Silicon 架构，`darwin-amd64` 适用于 Intel 架构. - -- **对于 FreeBSD**，`freebsd12-amd64` 适用于 64-bit 的 Intel/AMD 平台。 - -### 使用 wget 下载 - -使用以下命令下载适用于 64-bit Linux 平台的二进制文件。 - -```sh -wget -O gitea https://dl.gitea.com/gitea/@version@/gitea-@version@-linux-amd64 -chmod +x gitea -``` - -## 验证 GPG 签名 - -Gitea 对打包的二进制文件使用 [GPG密钥](https://keys.openpgp.org/search?q=teabot%40gitea.io) 签名以防止篡改。 -请根据对应文件名 `.asc` 中包含的校验码检验文件的一致性。 - -```sh -gpg --keyserver keys.openpgp.org --recv 7C9E68152594688862D62AF62D9AE806EC1592E2 -gpg --verify gitea-@version@-linux-amd64.asc gitea-@version@-linux-amd64 -``` - -校验正确时的信息为 `Good signature from "Teabot <teabot@gitea.io>"`。 -校验错误时的信息为 `This key is not certified with a trusted signature!`。 - -## 服务器设置 - -**提示：** `GITEA_WORK_DIR` 表示 Gitea 工作的路径。以下路径可以通过 [环境变量](administration/environment-variables.md) 初始化。 - -### 准备环境 - -检查是否安装 Git。要求 Git 版本 >= 2.0。 - -```sh -git --version -``` - -创建用户（推荐使用名称 `git`） - -```sh -# On Ubuntu/Debian: -adduser \ - --system \ - --shell /bin/bash \ - --gecos 'Git Version Control' \ - --group \ - --disabled-password \ - --home /home/git \ - git - -# On Fedora/RHEL/CentOS: -groupadd --system git -adduser \ - --system \ - --shell /bin/bash \ - --comment 'Git Version Control' \ - --gid git \ - --home-dir /home/git \ - --create-home \ - git -``` - -### 创建工作路径 - -```sh -mkdir -p /var/lib/gitea/{custom,data,log} -chown -R git:git /var/lib/gitea/ -chmod -R 750 /var/lib/gitea/ -mkdir /etc/gitea -chown root:git /etc/gitea -chmod 770 /etc/gitea -``` - -> **注意：** 为了让 Web 安装程序可以写入配置文件，我们临时为 `/etc/gitea` 路径授予了组外用户 `git` 写入权限。建议在安装结束后将配置文件的权限设置为只读。 -> -> ```sh -> chmod 750 /etc/gitea -> chmod 640 /etc/gitea/app.ini -> ``` - -如果您不希望通过 Web 安装程序创建配置文件，可以将配置文件设置为仅供 Gitea 用户只读（owner/group `root:git`, mode `0640`）并手工创建配置文件： - -- 设置 `INSTALL_LOCK=true` 关闭安装界面 -- 手动配置数据库连接参数 -- 使用 `gitea generate secret` 创建 `SECRET_KEY` 和 `INTERNAL_TOKEN` -- 提供所有必要的密钥 - -详情参考 [命令行文档](administration/command-line.md) 中有关 `gitea generate secret` 的内容。 - -### 配置 Gitea 工作路径 - -**提示：** 如果使用 Systemd 管理 Gitea 的 Linux 服务，你可以采用 `WorkingDirectory` 参数来配置工作路径。 否则，使用环境变量 `GITEA_WORK_DIR` 来明确指出程序工作和数据存放路径。 - -```sh -export GITEA_WORK_DIR=/var/lib/gitea/ -``` - -### 复制二进制文件到全局位置 - -```sh -cp gitea /usr/local/bin/gitea -``` - -### 添加 bash/zsh 自动补全（从 1.19 版本开始） - -可以在 [`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete) 找到启用 bash 自动补全的脚本。可以将其复制到 `/usr/share/bash-completion/completions/gitea`，或在 `.bashrc` 中引用。 - -同样地，zsh 自动补全的脚本可以在 [`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete) 找到。您可以将其复制到 `/usr/share/zsh/_gitea`，或在您的 `.zshrc` 中引用。 - -具体情况可能会有所不同，这些脚本可能需要进一步的改进。 - -## 运行 Gitea - -完成以上步骤后，可以通过两种方式运行 Gitea： - -### 1. 创建服务自动启动 Gitea（推荐） - -学习创建 [Linux 服务](installation/run-as-service-in-ubuntu.md) - -### 2. 通过命令行终端运行 - -```sh -GITEA_WORK_DIR=/var/lib/gitea/ /usr/local/bin/gitea web -c /etc/gitea/app.ini -``` - -## 升级到最新版本 - -您可以通过停止程序，替换 `/usr/local/bin/gitea` 并重启来更新到新版本。直接替换可执行程序时不要更改或使用新的文件名称，以避免数据出错。 - -建议您在更新之前进行[备份](administration/backup-and-restore.md)。 - -如果您按照上述描述执行了安装步骤，二进制文件的通用名称应为 gitea。请勿更改此名称，即不要包含版本号。 - -### 1. 使用 systemd 重新启动 Gitea（推荐） - -我们建议使用 systemd 作为服务管理器，使用 `systemctl restart gitea` 安全地重启程序。 - -### 2. 非 systemd 重启方法 - -使用 SIGHUP 信号关闭程序：查询到 Gitea 程序的 PID，使用 `kill -1 $GITEA_PID`，或者 `killall -1 gitea`。 - -更优雅的停止指令可能包括 `kill $GITEA_PID` 或者 `killall gitea`。 - -**提示：** 我们不建议使用 SIGKILL 信号（`-9`），这会强制停止 Gitea 程序，但不会正确关闭队列、索引器等任务。 - -请参阅下面的疑难解答说明，以在Gitea版本更新后修复损坏的仓库。 - -## 排查故障 - -### 旧版 glibc - -旧版 Linux 发行版（例如 Debian 7 和 CentOS 6）可能无法加载 Gitea 二进制文件，通常会产生类似于 `./gitea: /lib/x86_64-linux-gnu/libc.so.6: -version 'GLIBC\_2.14' not found (required by ./gitea)` 的错误。这是由于 dl.gitea.com 提供的二进制文件中集成了 SQLite 支持。在这种情况下，通常可以选择[从源代码安装](installation/from-source.md)，而不包括 SQLite 支持。 - -### 在另一个端口上运行 Gitea - -对于出现类似于 `702 runWeb()] [E] Failed to start server: listen tcp 0.0.0.0:3000: -bind: address already in use` 的错误，需要将 Gitea 启动在另一个空闲端口上。您可以使用 `./gitea web -p $PORT` 来实现。可能已经有另一个 Gitea 实例在运行。 - -### 在 Raspbian 上运行 Gitea - -从 v1.8 版本开始，arm7 版本的 Gitea 存在问题，无法在树莓派和类似设备上运行。 - -建议切换到 arm6 版本，该版本经过测试并已被证明可以在树莓派和类似设备上运行。 - -### 更新到新版本的 Gitea 后出现的 Git 错误 - -如果在更新过程中，二进制文件的名称已更改为新版本的 Gitea，则现有仓库中的 Git 钩子将不再起作用。在这种情况下，当推送到仓库时，会显示 Git 错误。 - -``` -remote: ./hooks/pre-receive.d/gitea: line 2: [...]: No such file or directory -``` - -错误信息中的 `[...]` 部分将包含您先前 Gitea 二进制文件的路径。 - -要解决此问题，请转到管理选项，并运行任务 `Resynchronize pre-receive, update and post-receive hooks of all repositories`，以将所有钩子更新为包含新的二进制文件路径。请注意，这将覆盖所有 Git 钩子，包括自定义的钩子。 - -如果您没有使用 Gitea 内置的 SSH 服务器，您还需要通过在管理选项中运行任务 `Update the '.ssh/authorized_keys' file with Gitea SSH keys.` 来重新编写授权密钥文件。 - -> 更多经验总结，请参考英文版 [Troubleshooting](https://docs.gitea.com/installation/install-from-binary#troubleshooting) - -如果从本页中没有找到你需要的内容，请访问 [帮助页面](help/support.md) diff --git a/docs/content/installation/from-package.en-us.md b/docs/content/installation/from-package.en-us.md deleted file mode 100644 index aceb2029d2..0000000000 --- a/docs/content/installation/from-package.en-us.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -date: "2016-12-01T16:00:00+02:00" -title: "Installation from package" -slug: "install-from-package" -sidebar_position: 20 -toc: false -draft: false -aliases: - - /en-us/install-from-package -menu: - sidebar: - parent: "installation" - name: "From package" - sidebar_position: 20 - identifier: "install-from-package" ---- - -# Installation from Package - -## Official packages - -### macOS - -Currently, the only supported method of installation on MacOS is [Homebrew](http://brew.sh/). -Following the [deployment from binary](installation/from-binary.md) guide may work, -but is not supported. To install Gitea via `brew`: - -``` -brew install gitea -``` - -## Unofficial packages - -### Alpine Linux - -Alpine Linux has [Gitea](https://pkgs.alpinelinux.org/packages?name=gitea&branch=edge) in its community repository which follows the latest stable version. - -```sh -apk add gitea -``` - -### Arch Linux - -The rolling release distribution has [Gitea](https://www.archlinux.org/packages/extra/x86_64/gitea/) in their official extra repository and package updates are provided with new Gitea releases. - -```sh -pacman -S gitea -``` - -### Arch Linux ARM - -Arch Linux ARM provides packages for [aarch64](https://archlinuxarm.org/packages/aarch64/gitea), [armv7h](https://archlinuxarm.org/packages/armv7h/gitea) and [armv6h](https://archlinuxarm.org/packages/armv6h/gitea). - -```sh -pacman -S gitea -``` - -### Gentoo Linux - -The rolling release distribution has [Gitea](https://packages.gentoo.org/packages/www-apps/gitea) in their official community repository and package updates are provided with new Gitea releases. - -```sh -emerge gitea -va -``` - -### Canonical Snap - -There is a [Gitea Snap](https://snapcraft.io/gitea) package which follows the latest stable version. -*Note: The Gitea snap package is [strictly confined](https://snapcraft.io/docs/snap-confinement). Strictly confined snaps run in complete isolation, so some of the Gitea functionals may not work with the confinement* - -```sh -snap install gitea -``` - -### SUSE and openSUSE - -OpenSUSE build service provides packages for [openSUSE and SLE](https://software.opensuse.org/download/package?package=gitea&project=devel%3Atools%3Ascm) -in the Development Software Configuration Management Repository - -### Windows - -There is a [Gitea](https://chocolatey.org/packages/gitea) package for Windows by [Chocolatey](https://chocolatey.org/). - -```sh -choco install gitea -``` - -Or follow the [deployment from binary](installation/from-binary.md) guide. - -### FreeBSD - -A FreeBSD port `www/gitea` is available. To install the pre-built binary package: - -``` -pkg install gitea -``` - -For the most up to date version, or to build the port with custom options, -[install it from the port](https://www.freebsd.org/doc/handbook/ports-using.html): - -``` -su - -cd /usr/ports/www/gitea -make install clean -``` - -The port uses the standard FreeBSD file system layout: config files are in `/usr/local/etc/gitea`, -bundled templates, options, plugins and themes are in `/usr/local/share/gitea`, and a start script -is in `/usr/local/etc/rc.d/gitea`. - -To enable Gitea to run as a service, run `sysrc gitea_enable=YES` and start it with `service gitea start`. - -### Others - -Various other third-party packages of Gitea exist. -To see a curated list, head over to [awesome-gitea](https://gitea.com/gitea/awesome-gitea/src/branch/master/README.md#user-content-packages). - -Do you know of an existing package that isn't on the list? Send in a PR to get it added! diff --git a/docs/content/installation/from-package.zh-cn.md b/docs/content/installation/from-package.zh-cn.md deleted file mode 100644 index 929782f23c..0000000000 --- a/docs/content/installation/from-package.zh-cn.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -date: "2016-12-01T16:00:00+02:00" -title: "使用包管理器安装" -slug: "install-from-package" -sidebar_position: 20 -toc: false -draft: false -aliases: - - /zh-cn/install-from-package -menu: - sidebar: - parent: "installation" - name: "使用包管理器安装" - sidebar_position: 20 - identifier: "install-from-package" ---- - -# 官方包管理器 - -## macOS - -macOS 平台下当前我们仅支持通过 `brew` 来安装。如果你没有安装 [Homebrew](http://brew.sh/)，你也可以查看 [从二进制安装](installation/from-binary.md)。在你安装了 `brew` 之后， 你可以执行以下命令： - -``` -brew install gitea -``` - -# 非官方包管理器 - -## Alpine Linux - -Gitea 已经包含在 Alpine Linux 的[社区存储库](https://pkgs.alpinelinux.org/packages?name=gitea&branch=edge)中，版本与 Gitea 官方保持同步。 - -```sh -apk add gitea -``` - -## Arch Linux - -Gitea 已经在滚动发布发行版的官方[社区存储库](https://www.archlinux.org/packages/community/x86_64/gitea/)中，版本与 Gitea 官方保持同步。 - -```sh -pacman -S gitea -``` - -## Arch Linux ARM - -官方支持 [aarch64](https://archlinuxarm.org/packages/aarch64/gitea)， [armv7h](https://archlinuxarm.org/packages/armv7h/gitea) 和 [armv6h](https://archlinuxarm.org/packages/armv6h/gitea) 架构。 - -```sh -pacman -S gitea -``` - -## Gentoo Linux - -滚动发布的发行版在其官方社区软件仓库中提供了 [Gitea](https://packages.gentoo.org/packages/www-apps/gitea)，并且会随着新的 Gitea 发布提供软件包更新。 - -```sh -emerge gitea -va -``` - -## Canonical Snap - -目前 Gitea 已在 Snap Store 中发布，名称为 [gitea](https://snapcraft.io/gitea)。 - -```sh -snap install gitea -``` - -## SUSE/openSUSE - -OpenSUSE 构建服务为 [openSUSE 和 SLE](https://software.opensuse.org/download/package?package=gitea&project=devel%3Atools%3Ascm) -提供包，你可以在开发软件配置管理存储库中找到它们。 - -## Windows - -目前你可以通过 [Chocolatey](https://chocolatey.org/) 来安装 [Gitea](https://chocolatey.org/packages/gitea)。 - -```sh -choco install gitea -``` - -你也可以 [从二进制安装](installation/from-binary.md) 。 - -## FreeBSD - -可以使用 Gitea 的 FreeBSD port `www/gitea`。 请安装预构建的二进制包： - -``` -pkg install gitea -``` - -对于最新版本，或使用自定义选项构建 port，请 -[从 port 安装](https://www.freebsd.org/doc/handbook/ports-using.html)： - -``` -su - -cd /usr/ports/www/gitea -make install clean -``` - -该 port 使用标准的 FreeBSD 文件系统布局：配置文件在 `/usr/local/etc/gitea` 目录中， -模板、选项、插件和主题在 `/usr/local/share/gitea` 目录中，启动脚本在 `/usr/local/etc/rc.d/gitea` 目录中。 - -要使 Gitea 作为服务运行，请运行 `sysrc gitea_enable=YES` 并使用 `service gitea start` 命令启动它。 - -## 第三方 - -如果这里没有找到你喜欢的包管理器，可以使用 Gitea 第三方软件包。这里有一个完整的列表： [awesome-gitea](https://gitea.com/gitea/awesome-gitea/src/branch/master/README.md#user-content-packages)。 - -如果你知道其他 Gitea 第三方软件包，请发送 PR 来添加它。 diff --git a/docs/content/installation/from-source.en-us.md b/docs/content/installation/from-source.en-us.md deleted file mode 100644 index cd9fd56511..0000000000 --- a/docs/content/installation/from-source.en-us.md +++ /dev/null @@ -1,262 +0,0 @@ ---- -date: "2016-12-01T16:00:00+02:00" -title: "Installation from source" -slug: "install-from-source" -sidebar_position: 30 -toc: false -draft: false -aliases: - - /en-us/install-from-source -menu: - sidebar: - parent: "installation" - name: "From source" - sidebar_position: 30 - identifier: "install-from-source" ---- - -# Installation from source - -You should [install go](https://go.dev/doc/install) and set up your go -environment correctly. In particular, it is recommended to set the `$GOPATH` -environment variable and to add the go bin directory or directories -`${GOPATH//://bin:}/bin` to the `$PATH`. See the Go wiki entry for -[GOPATH](https://github.com/golang/go/wiki/GOPATH). - -Next, [install Node.js with npm](https://nodejs.org/en/download/) which is -required to build the JavaScript and CSS files. The minimum supported Node.js -version is @minNodeVersion@ and the latest LTS version is recommended. - -**Note**: Go version @minGoVersion@ or higher is required. However, it is recommended to -obtain the same version as our continuous integration, see the advice given in -[Hacking on Gitea](development/hacking-on-gitea.md) - -## Download - -First, we must retrieve the source code. Since, the advent of go modules, the -simplest way of doing this is to use Git directly as we no longer have to have -Gitea built from within the GOPATH. - -```bash -git clone https://github.com/go-gitea/gitea -``` - -(Previous versions of this document recommended using `go get`. This is -no longer necessary.) - -Decide which version of Gitea to build and install. Currently, there are -multiple options to choose from. The `main` branch represents the current -development version. To build with main, skip to the [build section](#build). - -To work with tagged releases, the following commands can be used: - -```bash -git branch -a -git checkout v@version@ -``` - -To validate a Pull Request, first enable the new branch (`xyz` is the PR id; -for example `2663` for [#2663](https://github.com/go-gitea/gitea/pull/2663)): - -```bash -git fetch origin pull/xyz/head:pr-xyz -``` - -To build Gitea from source at a specific tagged release (like v@version@), list the -available tags and check out the specific tag. - -List available tags with the following. - -```bash -git tag -l -git checkout v@version@ # or git checkout pr-xyz -``` - -## Build - -To build from source, the following programs must be present on the system: - -- `go` @minGoVersion@ or higher, see [here](https://go.dev/dl/) -- `node` @minNodeVersion@ or higher with `npm`, see [here](https://nodejs.org/en/download/) -- `make`, see [here](development/hacking-on-gitea.md#installing-make) - -Various [make tasks](https://github.com/go-gitea/gitea/blob/main/Makefile) -are provided to keep the build process as simple as possible. - -Depending on requirements, the following build tags can be included. - -- `bindata`: Build a single monolithic binary, with all assets included. Required for production build. -- `sqlite sqlite_unlock_notify`: Enable support for a - [SQLite3](https://sqlite.org/) database. Suggested only for tiny - installations. -- `pam`: Enable support for PAM (Linux Pluggable Authentication Modules). Can - be used to authenticate local users or extend authentication to methods - available to PAM. -- `gogit`: (EXPERIMENTAL) Use go-git variants of Git commands. - -Bundling all assets (JS/CSS/templates, etc) into the binary. Using the `bindata` build tag is required for -production deployments. You could exclude `bindata` when you are developing/testing Gitea or able to separate the assets correctly. - -To include all assets, use the `bindata` tag: - -```bash -TAGS="bindata" make build -``` - -In the default release build of our continuous integration system, the build -tags are: `TAGS="bindata sqlite sqlite_unlock_notify"`. The simplest -recommended way to build from source is therefore: - -```bash -TAGS="bindata sqlite sqlite_unlock_notify" make build -``` - -The `build` target is split into two sub-targets: - -- `make backend` which requires [Go @minGoVersion@](https://go.dev/dl/) or greater. -- `make frontend` which requires [Node.js @minNodeVersion@](https://nodejs.org/en/download/) or greater. - -If pre-built frontend files are present it is possible to only build the backend: - -```bash -TAGS="bindata" make backend -``` - -## Test - -After following the steps above, a `gitea` binary will be available in the working directory. -It can be tested from this directory or moved to a directory with test data. When Gitea is -launched manually from command line, it can be killed by pressing `Ctrl + C`. - -```bash -./gitea web -``` - -## Changing default paths - -Gitea will search for a number of things from the _`CustomPath`_. By default this is -the `custom/` directory in the current working directory when running Gitea. It will also -look for its configuration file _`CustomConf`_ in `$(CustomPath)/conf/app.ini`, and will use the -current working directory as the relative base path _`AppWorkPath`_ for a number configurable -values. Finally the static files will be served from _`StaticRootPath`_ which defaults to the _`AppWorkPath`_. - -These values, although useful when developing, may conflict with downstream users preferences. - -One option is to use a script file to shadow the `gitea` binary and create an appropriate -environment before running Gitea. However, when building you can change these defaults -using the `LDFLAGS` environment variable for `make`. The appropriate settings are as follows - -- To set the _`CustomPath`_ use `LDFLAGS="-X \"code.gitea.io/gitea/modules/setting.CustomPath=custom-path\""` -- For _`CustomConf`_ you should use `-X \"code.gitea.io/gitea/modules/setting.CustomConf=conf.ini\"` -- For _`AppWorkPath`_ you should use `-X \"code.gitea.io/gitea/modules/setting.AppWorkPath=working-path\"` -- For _`StaticRootPath`_ you should use `-X \"code.gitea.io/gitea/modules/setting.StaticRootPath=static-root-path\"` -- To change the default PID file location use `-X \"code.gitea.io/gitea/cmd.PIDFile=/run/gitea.pid\"` - -Add as many of the strings with their preceding `-X` to the `LDFLAGS` variable and run `make build` -with the appropriate `TAGS` as above. - -Running `gitea help` will allow you to review what the computed settings will be for your `gitea`. - -## Cross Build - -The `go` compiler toolchain supports cross-compiling to different architecture targets that are supported by the toolchain. See [`GOOS` and `GOARCH` environment variable](https://go.dev/doc/install/source#environment) for the list of supported targets. Cross compilation is helpful if you want to build Gitea for less-powerful systems (such as Raspberry Pi). - -To cross build Gitea with build tags (`TAGS`), you also need a C cross compiler which targets the same architecture as selected by the `GOOS` and `GOARCH` variables. For example, to cross build for Linux ARM64 (`GOOS=linux` and `GOARCH=arm64`), you need the `aarch64-unknown-linux-gnu-gcc` cross compiler. This is required because Gitea build tags uses `cgo`'s foreign-function interface (FFI). - -Cross-build Gitea for Linux ARM64, without any tags: - -``` -GOOS=linux GOARCH=arm64 make build -``` - -Cross-build Gitea for Linux ARM64, with recommended build tags: - -``` -CC=aarch64-unknown-linux-gnu-gcc GOOS=linux GOARCH=arm64 TAGS="bindata sqlite sqlite_unlock_notify" make build -``` - -Replace `CC`, `GOOS`, and `GOARCH` as appropriate for your architecture target. - -You will sometimes need to build a static compiled image. To do this you will need to add: - -``` -LDFLAGS="-linkmode external -extldflags '-static' $LDFLAGS" TAGS="netgo osusergo $TAGS" make build -``` - -This can be combined with `CC`, `GOOS`, and `GOARCH` as above. - -### Adding bash/zsh autocompletion (from 1.19) - -A script to enable bash-completion can be found at [`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete). This should be altered as appropriate and can be `source` in your `.bashrc` -or copied as `/usr/share/bash-completion/completions/gitea`. - -Similarly, a script for zsh-completion can be found at [`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete). This can be copied to `/usr/share/zsh/_gitea` or sourced within your -`.zshrc`. - -YMMV and these scripts may need further improvement. - -## Compile or cross-compile using Linux with Zig - -Follow [Getting Started of Zig](https://ziglang.org/learn/getting-started/#installing-zig) to install zig. - -- Compile (Linux ➝ Linux) - -```sh -CC="zig cc -target x86_64-linux-gnu" \ -CGO_ENABLED=1 \ -CGO_CFLAGS="-O2 -g -pthread" \ -CGO_LDFLAGS="-linkmode=external -v" -GOOS=linux \ -GOARCH=amd64 \ -TAGS="bindata sqlite sqlite_unlock_notify" \ -make build -``` - -- Cross-compile (Linux ➝ Windows) - -```sh -CC="zig cc -target x86_64-windows-gnu" \ -CGO_ENABLED=1 \ -CGO_CFLAGS="-O2 -g -pthread" \ -GOOS=windows \ -GOARCH=amd64 \ -TAGS="bindata sqlite sqlite_unlock_notify" \ -make build -``` - -## Compile or cross-compile with Zig using Windows - -Compile with `GIT BASH`. - -- Compile (Windows ➝ Windows) - -```sh -CC="zig cc -target x86_64-windows-gnu" \ -CGO_ENABLED=1 \ -CGO_CFLAGS="-O2 -g -pthread" \ -GOOS=windows \ -GOARCH=amd64 \ -TAGS="bindata sqlite sqlite_unlock_notify" \ -make build -``` - -- Cross-compile (Windows ➝ Linux) - -```sh -CC="zig cc -target x86_64-linux-gnu" \ -CGO_ENABLED=1 \ -CGO_CFLAGS="-O2 -g -pthread" \ -CGO_LDFLAGS="-linkmode=external -v" -GOOS=linux \ -GOARCH=amd64 \ -TAGS="bindata sqlite sqlite_unlock_notify" \ -make build -``` - -## Source Maps - -By default, gitea generates reduced source maps for frontend files to conserve space. This can be controlled with the `ENABLE_SOURCEMAP` environment variable: - -- `ENABLE_SOURCEMAP=true` generates all source maps, the default for development builds -- `ENABLE_SOURCEMAP=reduced` generates limited source maps, the default for production builds -- `ENABLE_SOURCEMAP=false` generates no source maps diff --git a/docs/content/installation/from-source.zh-cn.md b/docs/content/installation/from-source.zh-cn.md deleted file mode 100644 index 3ff7efb4ed..0000000000 --- a/docs/content/installation/from-source.zh-cn.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -date: "2016-12-01T16:00:00+02:00" -title: "使用源代码安装" -slug: "install-from-source" -sidebar_position: 30 -toc: false -draft: false -aliases: - - /zh-cn/install-from-source -menu: - sidebar: - parent: "installation" - name: "使用源代码安装" - sidebar_position: 30 - identifier: "install-from-source" ---- - -# 使用源代码安装 - -你需要 [安装Go](https://golang.google.cn/doc/install) 并正确设置Go环境。特别的，建议设置`$GOPATH`环境变量，并将 Go 的二进制目录或目录`${GOPATH//://bin:}/bin`添加到`$PATH`中。请参阅 Go 百科上关于 [GOPATH](https://github.com/golang/go/wiki/GOPATH) 的词条。 - -接下来，[安装 Node.js 和 npm](https://nodejs.org/zh-cn/download/)， 这是构建 JavaScript 和 CSS 文件所需的。最低支持的 Node.js 版本是 @minNodeVersion@，建议使用最新的 LTS 版本。 - -**注意**：需要 Go 版本 @minGoVersion@ 或更高版本。不过，建议获取与我们的持续集成（continuous integration, CI）相同的版本，请参阅在 [Hacking on Gitea](development/hacking-on-gitea.md) 中给出的建议。 - -## 下载 - -首先，我们需要获取源码。由于引入了 Go 模块，最简单的方法是直接使用 Git，因为我们不再需要在 GOPATH 内构建 Gitea。 - -```bash -git clone https://github.com/go-gitea/gitea -``` - -（之前的版本中建议使用 `go get`，但现在不再需要。） - -你可以选择编译和安装的版本，当前有多个选择。`main` 分支代表当前的开发版本。如果你想编译 `main` 版本，你可以直接跳到 [构建](#构建) 部分。 - -如果你想编译带有标签的发行版本，可以使用以下命令签出： - -```bash -git branch -a -git checkout v@version@ -``` - -要验证一个拉取请求（Pull Request, PR），要先启用新的分支（其中 `xyz` 是 PR 的 ID；例如，对于 [#2663](https://github.com/go-gitea/gitea/pull/2663)，ID是 `2663 `）： - -```bash -git fetch origin pull/xyz/head:pr-xyz -``` - -要以指定发行版本（如 v@version@ ）的源代码来构建 Gitea，可执行以下命令列出可用的版本并选择某个版本签出。 -使用以下命令列出可用的版本： - -```bash -git tag -l -git checkout v@version@ # or git checkout pr-xyz -``` - -## 构建 - -要从源代码进行构建，系统必须预先安装以下程序： - -- `go` @minGoVersion@ 或更高版本，请参阅 [这里](https://go.dev/dl/) -- `node` @minNodeVersion@ 或更高版本，并且安装 `npm`, 请参阅 [这里](https://nodejs.org/zh-cn/download/) -- `make`, 请参阅 [这里](development/hacking-on-gitea.md) - -为了尽可能简化编译过程，提供了各种 [make任务](https://github.com/go-gitea/gitea/blob/main/Makefile)。 - -根据你的构建需求，以下 tags 可以使用： - -- `bindata`: 构建一个单一的整体二进制文件，包含所有资源。适用于构建生产环境版本。 -- `sqlite sqlite_unlock_notify`: 启用对 [SQLite3](https://sqlite.org/) 数据库的支持。仅建议在少数人使用时使用这个模式。 -- `pam`: 启用对 PAM（ Linux 可插拔认证模块）的支持。可用于对本地用户进行身份验证或扩展身份验证到 PAM 可用的方法。 -- `gogit`：（实验性功能）使用 go-git 变体的 Git 命令。 - -将所有资源（JS/CSS/模板等）打包到二进制文件中。在生产环境部署时，使用`bindata`构建标签是必需的。在开发/测试 Gitea 或能够明确分离资源时，可以不用`bindata`。 - -要包含所有资源，请使用 `bindata` 标签： - -```bash -TAGS="bindata" make build -``` - -在我们的持续集成系统的默认发行版中，构建标签为：`TAGS="bindata sqlite sqlite_unlock_notify"`。因此，从源码构建的最简单、推荐方式是： - -```bash -TAGS="bindata sqlite sqlite_unlock_notify" make build -``` - -`build`目标分为两个子目标： - -- `make backend` 需要 [Go @minGoVersion@](https://golang.google.cn/doc/install) 或更高版本。 -- `make frontend` 需要 [Node.js @minNodeVersion@](https://nodejs.org/zh-cn/download/) 或更高版本。 - -如果存在预构建的前端文件，可以仅构建后端： - -```bash -TAGS="bindata" make backend -``` - -## 测试 - -按照上述步骤完成后，工作目录中将会有一个`gitea`二进制文件。可以从该目录进行测试，或将其移动到带有测试数据的目录中。当手动从命令行启动 Gitea 时，可以通过按下`Ctrl + C`来停止程序。 - -```bash -./gitea web -``` - -## 更改默认路径 - -Gitea 将从`CustomPath`中查找许多信息。默认的，这会在运行 Gitea 时当前工作目录下的`custom/`目录中（译者案：即`$PATH_TO_YOUR_GITEA$/custom/`）。它还将在`$(CustomPath)/conf/app.ini`中查找其配置文件`CustomConf`，并将当前工作目录用作一些可配置值的相对基本路径`AppWorkPath`。最后，静态文件将从默认为 `AppWorkPath`的`StaticRootPath`提供。 - -尽管在开发时这些值很有用，但可能与下游用户的偏好冲突。 - -一种选择是使用脚本文件来隐藏`gitea`二进制文件，并在运行Gitea之前创建适当的环境。然而，在构建时，可以使用`make`的`LDFLAGS`环境变量来更改这些默认值。适当的设置如下： - -- 要设置`CustomPath`，请使用`LDFLAGS="-X \"code.gitea.io/gitea/modules/setting.CustomPath=custom-path\""` -- 对于`CustomConf`，应该使用`-X \"code.gitea.io/gitea/modules/setting.CustomConf=conf.ini\"` -- 对于`AppWorkPath`，应该使用`-X \"code.gitea.io/gitea/modules/setting.AppWorkPath=working-path\"` -- 对于`StaticRootPath`，应该使用`-X \"code.gitea.io/gitea/modules/setting.StaticRootPath=static-root-path\"` -- 要更改默认的 PID 文件位置，请使用`-X \"code.gitea.io/gitea/cmd.PIDFile=/run/gitea.pid\"` - -将这些字符串与其前导的`-X`添加到`LDFLAGS`变量中，并像上面那样使用适当的`TAGS`运行`make build`。 - -运行`gitea help`将允许您查看配置的`gitea`设置。 - -## 交叉编译 - -`go`编译器工具链支持将代码交叉编译到不同的目标架构上。请参考[`GOOS`和`GOARCH`环境变量](https://go.dev/doc/install/source#environment) 以获取支持的目标列表。如果您想为性能较弱的系统（如树莓派）构建 Gitea，交叉编译非常有用。 - -要使用构建标签（`TAGS`）进行交叉编译Gitea，您还需要一个 C 交叉编译器，该编译器的目标架构与`GOOS`和`GOARCH`变量选择的架构相同。例如，要为 Linux ARM64（`GOOS=linux`和`GOARCH=arm64`）进行交叉编译，您需要`aarch64-unknown-linux-gnu-gcc`交叉编译器。这是因为 Gitea 构建标签使用了`cgo`的外部函数接口（FFI）。 - -在没有任何标签的情况下，交叉编译的 Gitea 为 Linux ARM64 版本： - -``` -GOOS=linux GOARCH=arm64 make build -``` - -要交叉编译 Linux ARM64 下的Gitea，这是推荐的构建标签： - -``` -CC=aarch64-unknown-linux-gnu-gcc GOOS=linux GOARCH=arm64 TAGS="bindata sqlite sqlite_unlock_notify" make build -``` - -根据您的目标架构，适当替换`CC`、`GOOS`和`GOARCH`。 - -有时您需要构建一个静态编译的镜像。为此，您需要添加以下内容： - -``` -LDFLAGS="-linkmode external -extldflags '-static' $LDFLAGS" TAGS="netgo osusergo $TAGS" make build -``` - -这可以与上述的`CC`、`GOOS`和`GOARCH`结合使用。 - -### 添加 bash/zsh 自动补全（从 1.19 版本起） - -在[`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete)中可以找到一个启用 bash 自动补全的脚本。您可以根据需要进行修改，并在您的 `.bashrc` 中使用 `source` 命令加载该脚本，或者将其复制到 `/usr/share/bash-completion/completions/gitea`。 - -类似地，可以在[`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete)中找到一个用于 zsh 自动补全的脚本。您可以将其复制到 `/usr/share/zsh/_gitea`，或者在您的 `.zshrc` 中使用 `source` 命令加载该脚本。 - -可能需要你根据具体情况进一步改进这些脚本。 - -## 在 Linux 上使用 Zig 进行编译或交叉编译 - -请按照 [Zig 的入门指南](https://ziglang.org/learn/getting-started/#installing-zig) 安装 Zig。 - -- 编译 (Linux ➝ Linux) - -```sh -CC="zig cc -target x86_64-linux-gnu" \ -CGO_ENABLED=1 \ -CGO_CFLAGS="-O2 -g -pthread" \ -CGO_LDFLAGS="-linkmode=external -v" -GOOS=linux \ -GOARCH=amd64 \ -TAGS="bindata sqlite sqlite_unlock_notify" \ -make build -``` - -- 交叉编译 (Linux ➝ Windows) - -```sh -CC="zig cc -target x86_64-windows-gnu" \ -CGO_ENABLED=1 \ -CGO_CFLAGS="-O2 -g -pthread" \ -GOOS=windows \ -GOARCH=amd64 \ -TAGS="bindata sqlite sqlite_unlock_notify" \ -make build -``` - -## 在 Windows 上使用 Zig 进行编译或交叉编译 - -使用`GIT BASH`编译。 - -- 编译 (Windows ➝ Windows) - -```sh -CC="zig cc -target x86_64-windows-gnu" \ -CGO_ENABLED=1 \ -CGO_CFLAGS="-O2 -g -pthread" \ -GOOS=windows \ -GOARCH=amd64 \ -TAGS="bindata sqlite sqlite_unlock_notify" \ -make build -``` - -- 交叉编译 (Windows ➝ Linux) - -```sh -CC="zig cc -target x86_64-linux-gnu" \ -CGO_ENABLED=1 \ -CGO_CFLAGS="-O2 -g -pthread" \ -CGO_LDFLAGS="-linkmode=external -v" -GOOS=linux \ -GOARCH=amd64 \ -TAGS="bindata sqlite sqlite_unlock_notify" \ -make build -``` - -## Source Map - -默认情况下，gitea 会为前端文件生成精简的 Source Map 以节省空间。 这可以通过“ENABLE_SOURCEMAP”环境变量进行控制： - -- `ENABLE_SOURCEMAP=true` 生成所有Source Map，这是开发版本的默认设置 -- `ENABLE_SOURCEMAP=reduced` 生成有限的Source Map，这是生产版本的默认设置 -- `ENABLE_SOURCEMAP=false` 不生成Source Map diff --git a/docs/content/installation/on-cloud-provider.en-us.md b/docs/content/installation/on-cloud-provider.en-us.md deleted file mode 100644 index d5baece8ca..0000000000 --- a/docs/content/installation/on-cloud-provider.en-us.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -date: "2016-12-01T16:00:00+02:00" -title: "Install on Cloud Provider" -slug: "install-on-cloud-provider" -sidebar_position: 90 -toc: false -draft: false -aliases: - - /en-us/install-on-cloud-provider -menu: - sidebar: - parent: "installation" - name: "On cloud provider" - sidebar_position: 90 - identifier: "install-on-cloud-provider" ---- - -# Installation on Cloud Provider - -## Cloudron - -Gitea is available as a 1-click install on [Cloudron](https://cloudron.io). -Cloudron makes it easy to run apps like Gitea on your server and keep them up-to-date and secure. - -[](https://cloudron.io/button.html?app=io.gitea.cloudronapp) - -The Gitea package is maintained [here](https://git.cloudron.io/cloudron/gitea-app). - -There is a [demo instance](https://my.demo.cloudron.io) (username: cloudron password: cloudron) where -you can experiment with running Gitea. - -## Vultr - -Gitea can be found in [Vultr](https://www.vultr.com)'s marketplace. - -To deploy Gitea to Vultr, have a look at the [Vultr Marketplace](https://www.vultr.com/marketplace/apps/gitea). - -## DigitalOcean - -[DigitalOcean](https://www.digitalocean.com) has Gitea as droplet in their marketplace. - -To deploy Gitea to DigitalOcean, have a look at the [DigitalOcean Marketplace](https://marketplace.digitalocean.com/apps/gitea). - -## Linode - -[Linode](https://www.linode.com/) has Gitea as an app in their marketplace. - -To deploy Gitea to Linode, have a look at the [Linode Marketplace](https://www.linode.com/marketplace/apps/linode/gitea/). - -## alwaysdata - -[alwaysdata](https://www.alwaysdata.com/) has Gitea as an app in their marketplace. - -To deploy Gitea to alwaysdata, have a look at the [alwaysdata Marketplace](https://www.alwaysdata.com/en/marketplace/gitea/). - -## Exoscale - -[Exoscale](https://www.exoscale.com/) provides Gitea managed by [Glasskube](https://glasskube.eu/) in their marketplace. - -Exoscale is a European cloud service provider. - -The package is maintained and update via the open source [Glasskube Kubernetes Operator](https://github.com/glasskube/operator). - -To deploy Gitea to Exoscale, have a look at the [Exoscale Marketplace](https://www.exoscale.com/marketplace/listing/glasskube-gitea/). diff --git a/docs/content/installation/on-cloud-provider.zh-cn.md b/docs/content/installation/on-cloud-provider.zh-cn.md deleted file mode 100644 index 7b9a7bdf40..0000000000 --- a/docs/content/installation/on-cloud-provider.zh-cn.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -date: "2016-12-01T16:00:00+02:00" -title: "在云服务器中安装 Gitea" -slug: "install-on-cloud-provider" -sidebar_position: 90 -toc: false -draft: false -aliases: - - /zh-cn/install-on-cloud-provider -menu: - sidebar: - parent: "installation" - name: "在云服务器中安装 Gitea" - sidebar_position: 90 - identifier: "install-on-cloud-provider" ---- - -# 在云服务器上安装 Gitea - -## Cloudron - -Gitea 可以在 [Cloudron](https://cloudron.io) 上进行一键安装。 -Cloudron 使得在您的服务器上运行 Gitea，并保持其更新和安全变得简单。 - -[](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/). - -## Exoscale - -[Exoscale](https://www.exoscale.com/) 在其市场中提供由 [Glasskube](https://glasskube.eu/) 管理的 Gitea。 - -Exoscale 是一家欧洲的云服务提供商。 - -该软件包通过开源的 [Glasskube Kubernetes Operator](https://github.com/glasskube/operator) 进行维护和更新。 - -要在 Exoscale 上部署 Gitea，请参考 [Exoscale Marketplace](https://www.exoscale.com/marketplace/listing/glasskube-gitea/)。 diff --git a/docs/content/installation/on-kubernetes.en-us.md b/docs/content/installation/on-kubernetes.en-us.md deleted file mode 100644 index 00f2aab28d..0000000000 --- a/docs/content/installation/on-kubernetes.en-us.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -date: "2020-03-19T19:27:00+02:00" -title: "Install on Kubernetes" -slug: "install-on-kubernetes" -sidebar_position: 80 -toc: false -draft: false -aliases: - - /en-us/install-on-kubernetes -menu: - sidebar: - parent: "installation" - name: "Kubernetes" - sidebar_position: 80 - identifier: "install-on-kubernetes" ---- - -# Installation with Helm (on Kubernetes) - -Gitea provides a Helm Chart to allow for installation on kubernetes. - -A non-customized install can be done with: - -``` -helm repo add gitea-charts https://dl.gitea.com/charts/ -helm install gitea gitea-charts/gitea -``` - -If you would like to customize your install, which includes kubernetes ingress, please refer to the complete [Gitea helm chart configuration details](https://gitea.com/gitea/helm-chart/) - -## Health check endpoint - -Gitea comes with a health check endpoint `/api/healthz`, you can configure it in kubernetes like this: - -```yaml - livenessProbe: - httpGet: - path: /api/healthz - port: http - initialDelaySeconds: 200 - timeoutSeconds: 5 - periodSeconds: 10 - successThreshold: 1 - failureThreshold: 10 -``` - -a successful health check response will respond with http code `200`, here's example: - -``` -HTTP/1.1 200 OK - -{ - "status": "pass", - "description": "Gitea: Git with a cup of tea", - "checks": { - "cache:ping": [ - { - "status": "pass", - "time": "2022-02-19T09:16:08Z" - } - ], - "database:ping": [ - { - "status": "pass", - "time": "2022-02-19T09:16:08Z" - } - ] - } -} -``` - -for more information, please reference to kubernetes documentation [Define a liveness HTTP request](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-a-liveness-http-request) diff --git a/docs/content/installation/on-kubernetes.zh-cn.md b/docs/content/installation/on-kubernetes.zh-cn.md deleted file mode 100644 index 1af55d874b..0000000000 --- a/docs/content/installation/on-kubernetes.zh-cn.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -date: "2020-03-19T19:27:00+02:00" -title: "在 Kubernetes 中安装 Gitea" -slug: "install-on-kubernetes" -sidebar_position: 80 -toc: false -draft: false -aliases: - - /zh-cn/install-on-kubernetes -menu: - sidebar: - parent: "installation" - name: "在 Kubernetes 中安装 Gitea" - sidebar_position: 80 - identifier: "install-on-kubernetes" ---- - -# 使用 Helm 在 Kubernetes 云原生环境中安装 Gitea - -Gitea 已经提供了便于在 Kubernetes 云原生环境中安装所需的 Helm Chart - -默认安装指令为： - -```bash -helm repo add gitea https://dl.gitea.com/charts -helm repo update -helm install gitea gitea/gitea -``` - -如果采用默认安装指令，Helm 会部署单实例的 Gitea, PostgreSQL, Memcached。若您想实现自定义安装（包括配置 Gitea 集群、NGINX Ingress、MySQL、MariaDB、持久存储等），请前往阅读：[Gitea Helm Chart](https://gitea.com/gitea/helm-chart/) - -您也可以通过 `helm show` 命令导出 `README.md` 和配置文件 `values.yaml` 进行学习和编辑，例如： - -```bash -helm show values gitea/gitea > values.yaml -helm show readme gitea/gitea > README.md - -# 使用自定义的配置文件 values.yaml -helm install gitea -f values.yaml gitea/gitea -``` - -## 运行状况检查接口 - -Gitea 附带了一个运行状况检查接口 `/api/healthz`，你可以像这样在 Kubernetes 中配置它： - -```yaml - livenessProbe: - httpGet: - path: /api/healthz - port: http - initialDelaySeconds: 200 - timeoutSeconds: 5 - periodSeconds: 10 - successThreshold: 1 - failureThreshold: 10 -``` - -成功的运行状况检查响应代码为 HTTP `200`，下面是示例： - -``` -HTTP/1.1 200 OK - -{ - "status": "pass", - "description": "Gitea: Git with a cup of tea", - "checks": { - "cache:ping": [ - { - "status": "pass", - "time": "2022-02-19T09:16:08Z" - } - ], - "database:ping": [ - { - "status": "pass", - "time": "2022-02-19T09:16:08Z" - } - ] - } -} -``` - -有关更多信息，请参考 Kubernetes 文档 [配置存活、就绪和启动探测器](https://kubernetes.io/zh-cn/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/) diff --git a/docs/content/installation/run-as-service-in-ubuntu.en-us.md b/docs/content/installation/run-as-service-in-ubuntu.en-us.md deleted file mode 100644 index 4e169d6bcc..0000000000 --- a/docs/content/installation/run-as-service-in-ubuntu.en-us.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -date: "2017-07-21T12:00:00+02:00" -title: "Run as a Linux service" -slug: "linux-service" -sidebar_position: 40 -toc: false -draft: false -aliases: - - /en-us/linux-service -menu: - sidebar: - parent: "installation" - name: "Linux service" - sidebar_position: 40 - identifier: "linux-service" ---- - -# Run as a Linux service - -You can run Gitea as a Linux service, using either systemd or supervisor. The steps below tested on Ubuntu 16.04, but those should work on any Linux distributions (with little modification). - -## Using systemd - -Copy the sample [gitea.service](https://github.com/go-gitea/gitea/blob/main/contrib/systemd/gitea.service) to `/etc/systemd/system/gitea.service`, then edit the file with your favorite editor. - -Uncomment any service that needs to be enabled on this host, such as MySQL. - -Change the user, home directory, and other required startup values. Change the -PORT or remove the -p flag if default port is used. - -Enable and start Gitea at boot: - -``` -sudo systemctl enable gitea -sudo systemctl start gitea -``` - -If you have systemd version 220 or later, you can enable and immediately start Gitea at once by: - -``` -sudo systemctl enable gitea --now -``` - -## Using supervisor - -Install supervisor by running below command in terminal: - -``` -sudo apt install supervisor -``` - -Create a log dir for the supervisor logs: - -``` -# assuming Gitea is installed in /home/git/gitea/ -mkdir /home/git/gitea/log/supervisor -``` - -Append the configuration from the sample -[supervisord config](https://github.com/go-gitea/gitea/blob/main/contrib/supervisor/gitea) to `/etc/supervisor/supervisord.conf`. - -Using your favorite editor, change the user (`git`) and home -(`/home/git`) settings to match the deployment environment. Change the PORT -or remove the -p flag if default port is used. - -Lastly enable and start supervisor at boot: - -``` -sudo systemctl enable supervisor -sudo systemctl start supervisor -``` - -If you have systemd version 220 or later, you can enable and immediately start supervisor by: - -``` -sudo systemctl enable supervisor --now -``` diff --git a/docs/content/installation/run-as-service-in-ubuntu.zh-cn.md b/docs/content/installation/run-as-service-in-ubuntu.zh-cn.md deleted file mode 100644 index 6ec127c312..0000000000 --- a/docs/content/installation/run-as-service-in-ubuntu.zh-cn.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -date: "2017-07-21T12:00:00+02:00" -title: "在 Linux 中以 service 方式运行" -slug: "linux-service" -sidebar_position: 40 -toc: false -draft: false -aliases: - - /zh-cn/linux-service -menu: - sidebar: - parent: "installation" - name: "在Linux中以service方式运行" - sidebar_position: 40 - identifier: "linux-service" ---- - -### 在 Ubuntu 16.04 LTS 中以 service 方式运行 - -#### systemd 方式 - -在 terminal 中执行以下命令： - -``` -sudo vim /etc/systemd/system/gitea.service -``` - -接着拷贝示例代码 [gitea.service](https://github.com/go-gitea/gitea/blob/main/contrib/systemd/gitea.service) 并取消对任何需要运行在主机上的服务部分的注释，譬如 MySQL。 - -修改 user，home 目录以及其他必须的初始化参数，如果使用自定义端口，则需修改 PORT 参数，反之如果使用默认端口则需删除 -p 标记。 - -激活 gitea 并将它作为系统自启动服务： - -``` -sudo systemctl enable gitea -sudo systemctl start gitea -``` - -#### 使用 supervisor - -在 terminal 中执行以下命令安装 supervisor： - -``` -sudo apt install supervisor -``` - -为 supervisor 配置日志路径： - -``` -# assuming gitea is installed in /home/git/gitea/ -mkdir /home/git/gitea/log/supervisor -``` - -在文件编辑器中打开 supervisor 的配置文件： - -``` -sudo vim /etc/supervisor/supervisord.conf -``` - -增加如下示例配置 -[supervisord config](https://github.com/go-gitea/gitea/blob/main/contrib/supervisor/gitea)。 - -将 user(git) 和 home(/home/git) 设置为与上文部署中匹配的值。如果使用自定义端口，则需修改 PORT 参数，反之如果使用默认端口则需删除 -p 标记。 - -最后激活 supervisor 并将它作为系统自启动服务： - -``` -sudo systemctl enable supervisor -sudo systemctl start supervisor -``` diff --git a/docs/content/installation/upgrade-from-gitea.en-us.md b/docs/content/installation/upgrade-from-gitea.en-us.md deleted file mode 100644 index 4a5f21778a..0000000000 --- a/docs/content/installation/upgrade-from-gitea.en-us.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -date: "2021-09-02T16:00:00+08:00" -title: "Upgrade from an old Gitea" -slug: "upgrade-from-gitea" -sidebar_position: 100 -toc: false -draft: false -aliases: - - /en-us/upgrade-from-gitea -menu: - sidebar: - parent: "installation" - name: "Upgrade From Old Gitea" - sidebar_position: 100 - identifier: "upgrade-from-gitea" ---- - -# Upgrade from an old Gitea - -Follow below steps to ensure a smooth upgrade to a new Gitea version. - -## Check the Changelog for breaking changes - -To make Gitea better, some breaking changes are unavoidable, especially for big milestone releases. -Before upgrading, please read the [Changelog on Gitea blog](https://blog.gitea.com/) -and check whether the breaking changes affect your Gitea instance. - -## Verify there are no deprecated configuration options - -New versions of Gitea often come with changed configuration syntax or options which are usually displayed for -at least one release cycle inside at the top of the Site Administration panel. If these warnings are not -resolved, Gitea may refuse to start in the following version. - -## Backup for downgrade - -Gitea keeps compatibility for patch versions whose first two fields are the same (`a.b.x` -> `a.b.y`), -these patch versions can be upgraded and downgraded with the same database structure. -Otherwise (`a.b.?` -> `a.c.?`), a newer Gitea version will upgrade the old database -to a new structure that may differ from the old version. - -For example: - -| From | To | Result | -| --- | --- | --- | -| 1.4.0 | 1.4.1 | ✅ | -| 1.4.1 | 1.4.0 | ⚠️ Not recommended, take your own risk! Although it may work if the database structure doesn't change, it's highly recommended to use a backup to downgrade. | -| 1.4.x | 1.5.y | ✅ Database gets upgraded. You can upgrade from 1.4.x to the latest 1.5.y directly. | -| 1.5.y | 1.4.x | ❌ Database already got upgraded and can not be used for an old Gitea, use a backup to downgrade. | - -**Since you can not run an old Gitea with an upgraded database, -a backup should always be made before a database upgrade.** - -If you use Gitea in production, it's always highly recommended to make a backup before upgrade, -even if the upgrade is between patch versions. - -Backup steps: - -* Stop Gitea instance -* Backup database -* Backup Gitea config -* Backup Gitea data files in `APP_DATA_PATH` -* Backup Gitea external storage (eg: S3/MinIO or other storages if used) - -If you are using cloud services or filesystems with snapshot feature, -a snapshot for the Gitea data volume and related object storage is more convenient. - -After all of steps have been prepared, download the new version, stop the application, perform a backup and -then start the new application. On each startup, Gitea verifies that the database is up to date and will automatically -perform any necessary migrations. Depending on the size of the database, this can take some additional time on the -first launch during which the application will be unavailable. - -## Upgrade with Docker - -* `docker pull` the latest Gitea release. -* Stop the running instance, backup data. -* Use `docker` or `docker-compose` to start the newer Gitea Docker container. - -## Upgrade from package - -* Stop the running instance, backup data. -* Use your package manager to upgrade Gitea to the latest version. -* Start the Gitea instance. - -## Upgrade from binary - -* Download the latest Gitea binary to a temporary directory. -* Stop the running instance, backup data. -* Replace the installed Gitea binary with the downloaded one. -* Start the Gitea instance. - -A script automating these steps for a deployment on Linux can be found at [`contrib/upgrade.sh` in Gitea's source tree](https://github.com/go-gitea/gitea/blob/main/contrib/upgrade.sh). - -## Take care about customized templates - -Gitea's template structure and variables may change between releases, if you are using customized templates, -do pay attention if your templates are compatible with the Gitea you are using. - -If the customized templates don't match Gitea version, you may experience: -`50x` server error, page components missing or malfunctioning, strange page layout, ... -Remove or update the incompatible templates and Gitea web will work again. diff --git a/docs/content/installation/upgrade-from-gitea.zh-cn.md b/docs/content/installation/upgrade-from-gitea.zh-cn.md deleted file mode 100644 index 6300917e2d..0000000000 --- a/docs/content/installation/upgrade-from-gitea.zh-cn.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -date: "2021-09-02T16:00:00+08:00" -title: "从旧版 Gitea 升级" -slug: "upgrade-from-gitea" -sidebar_position: 100 -toc: false -draft: false -menu: - sidebar: - parent: "installation" - name: "从旧版 Gitea 升级" - sidebar_position: 100 - identifier: "upgrade-from-gitea" ---- - -# 从旧版 Gitea 升级 - -在升级之前，您需要做如下的准备工作。 - -## 为重大变更检查更新日志 - -为了让 Gitea 变得更好，进行重大变更是不可避免的，尤其是一些里程碑更新的发布。 -在更新前，请 [在 Gitea 博客上阅读更新日志](https://blog.gitea.com/) -并检查重大变更是否会影响你的 Gitea 实例。 - -## 在控制面板中检查过期的配置项 - -一些配置项可能会在后续版本中过期，你需要在控制面板中检查他们。如果不解决过期的配置项， -Gitea也许会在升级后无法重启。你可以访问 https://docs.gitea.com 获得要升级的版本 -对应的文档来修改你的配置文件。 - -## 降级前的备份 - -Gitea 会保留首二位版本号相同的版本的兼容性 (`a.b.x` -> `a.b.y`)， -这些版本拥有相同的数据库结构，可以自由升级或降级。 -其他情况 (`a.b.?` -> `a.c.?`)下， -新版 Gitea 可能将会将数据库升级到与旧版数据库不同的结构。 - -举个例子: - -| 当前 | 目标 | 结果 | -| --- | --- | --- | -| 1.4.0 | 1.4.1 | ✅ | -| 1.4.1 | 1.4.0 | ⚠️ 不建议，后果自负！尽管数据库结构可能不会变更，让它可以正常工作。我们强烈建议降级前进行完全的备份。 | -| 1.4.x | 1.5.y | ✅ 数据库会被自动升级。你可以直接从 1.4.x 升级到最新的 1.5.y。 | -| 1.5.y | 1.4.x | ❌ 数据库已被升级且无法用于旧版本Gitea，使用备份来进行降级。 | - -**因为你不能基于升级后的数据库运行旧版 Gitea，所以你应该在数据库升级前完成数据备份。** - -如果你在生产环境下使用 Gitea，你应该在升级前做好备份，哪怕只是小版本的补丁更新。 - -备份步骤: - -* 停止 Gitea 实例 -* 备份数据库 -* 备份 Gitea 配置文件 -* 备份 Gitea 在 `APP_DATA_PATH` 中的数据文件 -* 备份 Gitea 的外部存储 (例如: S3/MinIO 或被使用的其他存储) - -如果你在使用云服务或拥有快照功能的文件系统， -最好对 Gitea 的数据盘及相关资料存储进行一次快照。 - -在所有上述步骤准备妥当之后，要升级 Gitea，只需要下载新版，停止运行旧版，进行数据备份，然后运行新版就好。 -每次 Gitea 实例启动时，它都会检查是否要进行数据库迁移。 -如果需要进行数据库迁移，Gitea 会花一些时间完成升级然后继续服务。 - -## 从 Docker 升级 - -* `docker pull` 拉取 Gitea 的最新发布版。 -* 停止运行中的实例，备份数据。 -* 使用 `docker` 或 `docker-compose` 启动较新的 Gitea Docker 容器. - -## 从包升级 - -* 停止运行中的实例，备份数据。 -* 使用你的包管理器更新 Gitea 到最新版本。 -* 启动 Gitea 实例。 - -## 从二进制升级 - -* 下载最新的 Gitea 二进制文件到临时文件夹中。 -* 停止运行中的实例，备份数据。 -* 将旧的 Gitea 二进制文件覆盖成新的。 -* 启动 Gitea 实例。 - -在 Linux 系统上自动执行以上步骤的脚本可在 [Gitea 的 source tree 中找到 `contrib/upgrade.sh` 来获取](https://github.com/go-gitea/gitea/blob/main/contrib/upgrade.sh). - -## 小心你的自定义模板 - -Gitea 的模板结构与变量可能会随着各个版本的发布发生变化，如果你使用了自定义模板， -你得注意你的模板与你使用的 Gitea 版本的兼容性。 - -如果自定义模板与 Gitea 版本不兼容，你可能会遇到： -`50x` 服务器错误，页面元素丢失或故障，莫名其妙的页面布局，等等… -移除或更新不兼容的模板，Gitea Web 才可以正常工作。 diff --git a/docs/content/installation/windows-service.en-us.md b/docs/content/installation/windows-service.en-us.md deleted file mode 100644 index 6c7d372549..0000000000 --- a/docs/content/installation/windows-service.en-us.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -date: "2016-12-21T15:00:00-02:00" -title: "Register as a Windows service" -slug: "windows-service" -sidebar_position: 50 -toc: false -draft: false -aliases: - - /en-us/windows-service -menu: - sidebar: - parent: "installation" - name: "Windows Service" - sidebar_position: 50 - identifier: "windows-service" ---- -# Register as a Windows service - -## Prerequisites - -The following changes are made in C:\gitea\custom\conf\app.ini: - -``` -RUN_USER = COMPUTERNAME$ -``` - -Sets Gitea to run as the local system user. - -COMPUTERNAME is whatever the response is from `echo %COMPUTERNAME%` on the command line. If the response is `USER-PC` then `RUN_USER = USER-PC$` - -### Use absolute paths - -If you use SQLite3, change the `PATH` to include the full path: - -``` -[database] -PATH = c:/gitea/data/gitea.db -``` - -## Register Gitea - -To register Gitea as a Windows service, open a command prompt (cmd) as an Administrator, -then run the following command: - -``` -sc.exe create gitea start= auto binPath= "\"C:\gitea\gitea.exe\" web --config \"C:\gitea\custom\conf\app.ini\"" -``` - -Do not forget to replace `C:\gitea` with the correct Gitea directory. - -Open "Windows Services", search for the service named "gitea", right-click it and click on -"Run". If everything is OK, Gitea will be reachable on `http://localhost:3000` (or the port -that was configured). - -### Service startup type - -It was observed that on loaded systems during boot Gitea service may fail to start with timeout records in Windows Event Log. -In that case change startup type to `Automatic-Delayed`. This can be done during service creation, or by running config command - -``` -sc.exe config gitea start= delayed-auto -``` - -### Adding startup dependencies - -To add a startup dependency to the Gitea Windows service (eg Mysql, Mariadb), as an Administrator, then run the following command: - -``` -sc.exe config gitea depend= mariadb -``` - -This will ensure that when the Windows machine restarts, the automatic starting of Gitea is postponed until the database is ready and thus mitigate failed startups. - -## Unregister Gitea - -To unregister Gitea as a Windows service, open a command prompt (cmd) as an Administrator and run: - -``` -sc.exe delete gitea -``` diff --git a/docs/content/installation/windows-service.zh-cn.md b/docs/content/installation/windows-service.zh-cn.md deleted file mode 100644 index d5761d2c19..0000000000 --- a/docs/content/installation/windows-service.zh-cn.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -date: "2016-12-21T15:00:00-02:00" -title: "注册为Windows服务" -slug: "windows-service" -sidebar_position: 50 -toc: false -draft: false -aliases: - - /zh-cn/windows-service -menu: - sidebar: - parent: "installation" - name: "Windows服务" - sidebar_position: 50 - identifier: "windows-service" ---- - -## 准备工作 - -在 C:\gitea\custom\conf\app.ini 中进行了以下更改： - -``` -RUN_USER = COMPUTERNAME$ -``` - -将 Gitea 设置为以本地系统用户运行。 - -COMPUTERNAME 是从命令行中运行 `echo %COMPUTERNAME%` 后得到的响应。如果响应是 `USER-PC`，那么 `RUN_USER = USER-PC$`。 - -### 使用绝对路径 - -如果您使用 SQLite3，请将 `PATH` 更改为包含完整路径： - -``` -[database] -PATH = c:/gitea/data/gitea.db -``` - -## 注册为Windows服务 - -要注册为Windows服务，首先以Administrator身份运行 `cmd`，然后执行以下命令： - -``` -sc.exe create gitea start= auto binPath= "\"C:\gitea\gitea.exe\" web --config \"C:\gitea\custom\conf\app.ini\"" -``` - -别忘了将 `C:\gitea` 替换成你的 Gitea 安装目录。 - -之后在控制面板打开 "Windows Services"，搜索 "gitea"，右键选择 "Run"。在浏览器打开 `http://localhost:3000` 就可以访问了。（如果你修改了端口，请访问对应的端口，3000是默认端口）。 - -### 服务启动类型 - -据观察，在启动期间加载的系统上，Gitea 服务可能无法启动，并在 Windows 事件日志中记录超时。 -在这种情况下，将启动类型更改为`Automatic-Delayed`。这可以在服务创建期间完成，或者通过运行配置命令来完成。 - -``` -sc.exe config gitea start= delayed-auto -``` - -### 添加启动依赖项 - -要将启动依赖项添加到 Gitea Windows 服务（例如 Mysql、Mariadb），作为管理员，然后运行以下命令： - -``` -sc.exe config gitea depend= mariadb -``` - -这将确保在 Windows 计算机重新启动时，将延迟自动启动 Gitea，直到数据库准备就绪，从而减少启动失败的情况。 - -## 从Windows服务中删除 - -以Administrator身份运行 `cmd`，然后执行以下命令： - -``` -sc.exe delete gitea -``` diff --git a/docs/content/installation/with-docker-rootless.en-us.md b/docs/content/installation/with-docker-rootless.en-us.md deleted file mode 100644 index 10f1212217..0000000000 --- a/docs/content/installation/with-docker-rootless.en-us.md +++ /dev/null @@ -1,364 +0,0 @@ ---- -date: "2020-02-09T20:00:00+02:00" -title: "Installation with Docker (rootless)" -slug: "install-with-docker-rootless" -sidebar_position: 60 -toc: false -draft: false -aliases: - - /en-us/install-with-docker-rootless -menu: - sidebar: - parent: "installation" - name: "With Docker Rootless" - sidebar_position: 60 - identifier: "install-with-docker-rootless" ---- - -# Installation with Docker - -Gitea provides automatically updated Docker images within its Docker Hub organization. It is -possible to always use the latest stable tag or to use another service that handles updating -Docker images. - -The rootless image uses Gitea internal SSH to provide Git protocol and doesn't support OpenSSH. - -This reference setup guides users through the setup based on `docker-compose`, but the installation -of `docker-compose` is out of scope of this documentation. To install `docker-compose` itself, follow -the official [install instructions](https://docs.docker.com/compose/install/). - -## Basics - -The most simple setup just creates a volume and a network and starts the `gitea/gitea:latest-rootless` -image as a service. Since there is no database available, one can be initialized using SQLite3. - -Create a directory for `data` and `config`: - -```sh -mkdir -p gitea/{data,config} -cd gitea -touch docker-compose.yml -``` - -Then paste the following content into a file named `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" -``` - -Note that the volume should be owned by the user/group with the UID/GID specified in the config file. By default Gitea in docker will use uid:1000 gid:1000. If needed you can set ownership on those folders with the command: - -```sh -sudo chown 1000:1000 config/ data/ -``` - -> If you don't give the volume correct permissions, the container may not start. - -For a stable release you could use `:latest-rootless`, `:1-rootless` or specify a certain release like `:@version@-rootless`, but if you'd like to use the latest development version then `:nightly-rootless` would be an appropriate tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly-rootless` tag, where x is the minor version of Gitea. (e.g. `:1.16-nightly-rootless`) - -## Custom port - -To bind the integrated ssh and the webserver on a different port, adjust -the port section. It's common to just change the host port and keep the ports within -the container like they are. - -```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 database - -To start Gitea in combination with a MySQL database, apply these changes to the -`docker-compose.yml` file created above. - -```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" - - "2222:2222" -+ 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 database - -To start Gitea in combination with a PostgreSQL database, apply these changes to -the `docker-compose.yml` file created above. - -```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 - -To use named volumes instead of host volumes, define and use the named volume -within the `docker-compose.yml` configuration. This change will automatically -create the required volume. You don't need to worry about permissions with -named volumes; Docker will deal with that automatically. - -```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 or PostgreSQL containers will need to be created separately. - -## Custom user - -You can choose to use a custom user (following --user flag definition https://docs.docker.com/engine/reference/run/#user). -As an example to clone the host user `git` definition use the command `id -u git` and add it to `docker-compose.yml` file: -Please make sure that the mounted folders are writable by the user. - -```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" -``` - -## Start - -To start this setup based on `docker-compose`, execute `docker-compose up -d`, -to launch Gitea in the background. Using `docker-compose ps` will show if Gitea -started properly. Logs can be viewed with `docker-compose logs`. - -To shut down the setup, execute `docker-compose down`. This will stop -and kill the containers. The volumes will still exist. - -Notice: if using a non-3000 port on http, change app.ini to match -`LOCAL_ROOT_URL = http://localhost:3000/`. - -## Install - -After starting the Docker setup via `docker-compose`, Gitea should be available using a -favorite browser to finalize the installation. Visit http://server-ip:3000 and follow the -installation wizard. If the database was started with the `docker-compose` setup as -documented above, please note that `db` must be used as the database hostname. - -# Customization - -Customization files described [here](administration/customizing-gitea.md) should -be placed in `/var/lib/gitea/custom` directory. If using host volumes, it's quite easy to access these -files; for named volumes, this is done through another container or by direct access at -`/var/lib/docker/volumes/gitea_gitea/_/var_lib_gitea`. The configuration file will be saved at -`/etc/gitea/app.ini` after the installation. - -# Upgrading - -:exclamation::exclamation: **Make sure you have volumed data to somewhere outside Docker container** :exclamation::exclamation: - -To upgrade your installation to the latest release: - -``` -# Edit `docker-compose.yml` to update the version, if you have one specified -# Pull new images -docker-compose pull -# Start a new container, automatically removes old one -docker-compose up -d -``` - -# Upgrading from standard image - -- Backup your setup -- Change volume mountpoint from /data to /var/lib/gitea -- If you used a custom app.ini move it to a new volume mounted to /etc/gitea -- Rename folder (inside volume) gitea to custom -- Edit app.ini if needed - - Set START_SSH_SERVER = true -- Use image gitea/gitea:@version@-rootless - -## Managing Deployments With Environment Variables - -In addition to the environment variables above, any settings in `app.ini` can be set -or overridden with an environment variable of the form: `GITEA__SECTION_NAME__KEY_NAME`. -These settings are applied each time the docker container starts, and won't be passed into Gitea's sub-processes. -Full information [here](https://github.com/go-gitea/gitea/tree/main/contrib/environment-to-ini). - -These environment variables can be passed to the docker container in `docker-compose.yml`. -The following example will enable a smtp mail server if the required env variables -`GITEA__mailer__FROM`, `GITEA__mailer__HOST`, `GITEA__mailer__PASSWD` are set on the host -or in a `.env` file in the same directory as `docker-compose.yml`. - -The settings can be also set or overridden with the content of a file by defining an environment variable of the form: -`GITEA__section_name__KEY_NAME__FILE` that points to a file. - -```bash -... -services: - server: - environment: - - GITEA__mailer__ENABLED=true - - GITEA__mailer__FROM=${GITEA__mailer__FROM:?GITEA__mailer__FROM not set} - - GITEA__mailer__PROTOCOL=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}""" -``` - -To set required TOKEN and SECRET values, consider using Gitea's built-in [generate utility functions](administration/command-line.md#generate). - -# SSH Container Passthrough - -Since SSH is running inside the container, SSH needs to be passed through from the host to the container if SSH support is desired. One option would be to run the container SSH on a non-standard port (or moving the host port to a non-standard port). Another option which might be more straightforward is to forward SSH commands from the host to the container. This setup is explained in the following. - -This guide assumes that you have created a user on the host called `git` with permission to run `docker exec`, and that the Gitea container is called `gitea`. You will need to modify that user's shell to forward the commands to the `sh` executable inside the container, using `docker exec`. - -First, create the file `/usr/local/bin/gitea-shell` on the host, with the following contents: - -```bash -#!/bin/sh -/usr/bin/docker exec -i --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@" -``` - -Note that `gitea` in the docker command above is the name of the container. If you named yours differently, don't forget to change that. - -You should also make sure that you’ve set the permissions of the shell wrapper correctly: - -```bash -sudo chmod +x /usr/local/bin/gitea-shell -``` - -Once the wrapper is in place, you can make it the shell for the `git` user: - -```bash -sudo usermod -s /usr/local/bin/gitea-shell git -``` - -Now that all the SSH commands are forwarded to the container, you need to set up the SSH authentication on the host. This is done by leveraging the [SSH AuthorizedKeysCommand](administration/command-line.md#keys) to match the keys against those accepted by Gitea. Add the following block to `/etc/ssh/sshd_config`, on the host: - -```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 -``` - -(From 1.16.0 you will not need to set the `-c /etc/gitea/app.ini` option.) - -All that is left to do is restart the SSH server: - -```bash -sudo systemctl restart sshd -``` - -**Notes** - -This isn't actually using the docker SSH - it is simply using the commands around it. -You could theoretically not run the internal SSH server. diff --git a/docs/content/installation/with-docker-rootless.zh-cn.md b/docs/content/installation/with-docker-rootless.zh-cn.md deleted file mode 100644 index 70bc32dc12..0000000000 --- a/docs/content/installation/with-docker-rootless.zh-cn.md +++ /dev/null @@ -1,332 +0,0 @@ ---- -date: "2020-02-09T20:00:00+02:00" -title: "使用 Docker 安装 (rootless)" -slug: "install-with-docker-rootless" -sidebar_position: 60 -toc: false -draft: false -aliases: - - /zh-cn/install-with-docker-rootless -menu: - sidebar: - parent: "installation" - name: "使用 Docker 安装 (rootless)" - sidebar_position: 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__PROTOCOL=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 的内置[生成使用函数](administration/command-line.md#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](administration/command-line.md#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 服务器。 diff --git a/docs/content/installation/with-docker.en-us.md b/docs/content/installation/with-docker.en-us.md deleted file mode 100644 index a16d4a8d60..0000000000 --- a/docs/content/installation/with-docker.en-us.md +++ /dev/null @@ -1,643 +0,0 @@ ---- -date: "2020-03-19T19:27:00+02:00" -title: "Installation with Docker" -slug: "install-with-docker" -sidebar_position: 70 -toc: false -draft: false -aliases: - - /en-us/install-with-docker -menu: - sidebar: - parent: "installation" - name: "With Docker" - sidebar_position: 70 - identifier: "install-with-docker" ---- - -# Installation with Docker - -Gitea provides automatically updated Docker images within its Docker Hub organization. It is -possible to always use the latest stable tag or to use another service that handles updating -Docker images. - -This reference setup guides users through the setup based on `docker-compose`, but the installation -of `docker-compose` is out of scope of this documentation. To install `docker-compose` itself, follow -the official [install instructions](https://docs.docker.com/compose/install/). - -## Basics - -The most simple setup just creates a volume and a network and starts the `gitea/gitea:latest` -image as a service. Since there is no database available, one can be initialized using SQLite3. -Create a directory like `gitea` and paste the following content into a file named `docker-compose.yml`. -Note that the volume should be owned by the user/group with the UID/GID specified in the config file. -If you don't give the volume correct permissions, the container may not start. -For a stable release you can use `:latest`, `:1` or specify a certain release like `:@version@`, but if you'd like to use the latest development version of Gitea then you could use the `:nightly` tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly` tag, where x is the minor version of Gitea. (e.g. `:1.16-nightly`) - -```yaml -version: "3" - -networks: - gitea: - external: false - -services: - server: - image: gitea/gitea:@version@ - container_name: gitea - environment: - - USER_UID=1000 - - USER_GID=1000 - restart: always - networks: - - gitea - volumes: - - ./gitea:/data - - /etc/timezone:/etc/timezone:ro - - /etc/localtime:/etc/localtime:ro - ports: - - "3000:3000" - - "222:22" -``` - -## Ports - -To bind the integrated OpenSSH daemon and the webserver on a different port, adjust -the port section. It's common to just change the host port and keep the ports within -the container like they are. - -```diff -version: "3" - -networks: - gitea: - external: false - -services: - server: - image: gitea/gitea:@version@ - container_name: gitea - environment: - - USER_UID=1000 - - USER_GID=1000 - restart: always - networks: - - gitea - volumes: - - ./gitea:/data - - /etc/timezone:/etc/timezone:ro - - /etc/localtime:/etc/localtime:ro - ports: -- - "3000:3000" -- - "222:22" -+ - "8080:3000" -+ - "2221:22" -``` - -## Databases - -### MySQL database - -To start Gitea in combination with a MySQL database, apply these changes to the -`docker-compose.yml` file created above. - -```diff -version: "3" - -networks: - gitea: - external: false - -services: - server: - image: gitea/gitea:@version@ - container_name: gitea - environment: - - USER_UID=1000 - - USER_GID=1000 -+ - GITEA__database__DB_TYPE=mysql -+ - GITEA__database__HOST=db:3306 -+ - GITEA__database__NAME=gitea -+ - GITEA__database__USER=gitea -+ - GITEA__database__PASSWD=gitea - restart: always - networks: - - gitea - volumes: - - ./gitea:/data - - /etc/timezone:/etc/timezone:ro - - /etc/localtime:/etc/localtime:ro - ports: - - "3000:3000" - - "222:22" -+ depends_on: -+ - db -+ -+ db: -+ image: mysql:8 -+ restart: always -+ environment: -+ - MYSQL_ROOT_PASSWORD=gitea -+ - MYSQL_USER=gitea -+ - MYSQL_PASSWORD=gitea -+ - MYSQL_DATABASE=gitea -+ networks: -+ - gitea -+ volumes: -+ - ./mysql:/var/lib/mysql -``` - -### PostgreSQL database - -To start Gitea in combination with a PostgreSQL database, apply these changes to -the `docker-compose.yml` file created above. - -```diff -version: "3" - -networks: - gitea: - external: false - -services: - server: - image: gitea/gitea:@version@ - container_name: gitea - environment: - - USER_UID=1000 - - USER_GID=1000 -+ - GITEA__database__DB_TYPE=postgres -+ - GITEA__database__HOST=db:5432 -+ - GITEA__database__NAME=gitea -+ - GITEA__database__USER=gitea -+ - GITEA__database__PASSWD=gitea - restart: always - networks: - - gitea - volumes: - - ./gitea:/data - - /etc/timezone:/etc/timezone:ro - - /etc/localtime:/etc/localtime:ro - ports: - - "3000:3000" - - "222:22" -+ depends_on: -+ - db -+ -+ db: -+ image: postgres:14 -+ restart: always -+ environment: -+ - POSTGRES_USER=gitea -+ - POSTGRES_PASSWORD=gitea -+ - POSTGRES_DB=gitea -+ networks: -+ - gitea -+ volumes: -+ - ./postgres:/var/lib/postgresql/data -``` - -## Named volumes - -To use named volumes instead of host volumes, define and use the named volume -within the `docker-compose.yml` configuration. This change will automatically -create the required volume. You don't need to worry about permissions with -named volumes; Docker will deal with that automatically. - -```diff -version: "3" - -networks: - gitea: - external: false - -+volumes: -+ gitea: -+ driver: local -+ -services: - server: - image: gitea/gitea:@version@ - container_name: gitea - restart: always - networks: - - gitea - volumes: -- - ./gitea:/data -+ - gitea:/data - - /etc/timezone:/etc/timezone:ro - - /etc/localtime:/etc/localtime:ro - ports: - - "3000:3000" - - "222:22" -``` - -MySQL or PostgreSQL containers will need to be created separately. - -## Startup - -To start this setup based on `docker-compose`, execute `docker-compose up -d`, -to launch Gitea in the background. Using `docker-compose ps` will show if Gitea -started properly. Logs can be viewed with `docker-compose logs`. - -To shut down the setup, execute `docker-compose down`. This will stop -and kill the containers. The volumes will still exist. - -Notice: if using a non-3000 port on http, change app.ini to match -`LOCAL_ROOT_URL = http://localhost:3000/`. - -## Installation - -After starting the Docker setup via `docker-compose`, Gitea should be available using a -favorite browser to finalize the installation. Visit http://server-ip:3000 and follow the -installation wizard. If the database was started with the `docker-compose` setup as -documented above, please note that `db` must be used as the database hostname. - -## Configure the user inside Gitea using environment variables - -- `USER`: **git**: The username of the user that runs Gitea within the container. -- `USER_UID`: **1000**: The UID (Unix user ID) of the user that runs Gitea within the container. Match this to the UID of the owner of the `/data` volume if using host volumes (this is not necessary with named volumes). -- `USER_GID`: **1000**: The GID (Unix group ID) of the user that runs Gitea within the container. Match this to the GID of the owner of the `/data` volume if using host volumes (this is not necessary with named volumes). - -## Customization - -Customization files described [here](administration/customizing-gitea.md) should -be placed in `/data/gitea` directory. If using host volumes, it's quite easy to access these -files; for named volumes, this is done through another container or by direct access at -`/var/lib/docker/volumes/gitea_gitea/_data`. The configuration file will be saved at -`/data/gitea/conf/app.ini` after the installation. - -## Upgrading - -:exclamation::exclamation: **Make sure you have volumed data to somewhere outside Docker container** :exclamation::exclamation: - -To upgrade your installation to the latest release: - -```bash -# Edit `docker-compose.yml` to update the version, if you have one specified -# Pull new images -docker-compose pull -# Start a new container, automatically removes old one -docker-compose up -d -``` - -## Managing Deployments With Environment Variables - -In addition to the environment variables above, any settings in `app.ini` can be set -or overridden with an environment variable of the form: `GITEA__SECTION_NAME__KEY_NAME`. -These settings are applied each time the docker container starts, and won't be passed into Gitea's sub-processes. -Full information [here](https://github.com/go-gitea/gitea/tree/master/contrib/environment-to-ini). - -These environment variables can be passed to the docker container in `docker-compose.yml`. -The following example will enable an smtp mail server if the required env variables -`GITEA__mailer__FROM`, `GITEA__mailer__HOST`, `GITEA__mailer__PASSWD` are set on the host -or in a `.env` file in the same directory as `docker-compose.yml`. - -The settings can be also set or overridden with the content of a file by defining an environment variable of the form: -`GITEA__section_name__KEY_NAME__FILE` that points to a file. - -```bash -... -services: - server: - environment: - - GITEA__mailer__ENABLED=true - - GITEA__mailer__FROM=${GITEA__mailer__FROM:?GITEA__mailer__FROM not set} - - GITEA__mailer__PROTOCOL=smtps - - GITEA__mailer__SMTP_ADDR=${GITEA__mailer__SMTP_ADDR:?GITEA__mailer__SMTP_ADDR not set} - - GITEA__mailer__SMTP_PORT=${GITEA__mailer__SMTP_PORT:?GITEA__mailer__SMTP_PORT not set} - - GITEA__mailer__USER=${GITEA__mailer__USER:-apikey} - - GITEA__mailer__PASSWD="""${GITEA__mailer__PASSWD:?GITEA__mailer__PASSWD not set}""" -``` - -Gitea will generate new secrets/tokens for every new installation automatically and write them into the app.ini. If you want to set the secrets/tokens manually, you can use the following docker commands to use of Gitea's built-in [generate utility functions](administration/command-line.md#generate). Do not lose/change your SECRET_KEY after the installation, otherwise the encrypted data can not be decrypted anymore. - -The following commands will output a new `SECRET_KEY` and `INTERNAL_TOKEN` to `stdout`, which you can then place in your environment variables. - -```bash -docker run -it --rm gitea/gitea:1 gitea generate secret SECRET_KEY -docker run -it --rm gitea/gitea:1 gitea generate secret INTERNAL_TOKEN -``` - -```yaml -... -services: - server: - environment: - - GITEA__security__SECRET_KEY=[value returned by generate secret SECRET_KEY] - - GITEA__security__INTERNAL_TOKEN=[value returned by generate secret INTERNAL_TOKEN] -``` - -## SSH Container Passthrough - -Since SSH is running inside the container, SSH needs to be passed through from the host to the container if SSH support is desired. One option would be to run the container SSH on a non-standard port (or moving the host port to a non-standard port). Another option which might be more straightforward is for Gitea users to ssh to a Gitea user on the host which will then relay those connections to the docker. - -### Understanding SSH access to Gitea (without passthrough) - -To understand what needs to happen, you first need to understand what happens without passthrough. So we will try to explain this: - -1. The client adds their SSH public key to Gitea using the webpage. -2. Gitea will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`. -3. This entry has the public key, but also has a `command=` option. It is this command that Gitea uses to match this key to the client user and manages authentication. -4. The client then makes an SSH request to the SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`. -5. The client will attempt to authenticate with the server, passing one or more public keys one at a time to the server. -6. For each key the client provides, the SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the `git` user's `authorized_keys` file. -7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed. -8. The SSH server creates a user session for the `git` user, and using the shell for the `git` user runs the `command=` -9. This runs `gitea serv` which takes over control of the rest of the SSH session and manages gitea authentication & authorization of the git commands. - -Now, for the SSH passthrough to work, we need the host SSH to match the public keys and then run the `gitea serv` on the docker. There are multiple ways of doing this. However, all of these require some information about the docker being passed to the host. - -### SSHing Shim (with authorized_keys) - -In this option, the idea is that the host simply uses the `authorized_keys` that gitea creates but at step 9 the `gitea` command that the host runs is a shim that actually runs ssh to go into the docker and then run the real docker `gitea` itself. - -- To make the forwarding work, the SSH port of the container (22) needs to be mapped to the host port 2222 in `docker-compose.yml` . Since this port does not need to be exposed to the outside world, it can be mapped to the `localhost` of the host machine: - - ```yaml - ports: - # [...] - - "127.0.0.1:2222:22" - ``` - -- Next on the host create the `git` user which shares the same `UID`/ `GID` as the container values `USER_UID`/ `USER_GID`. These values can be set as environment variables in the `docker-compose.yml`: - - ```yaml - environment: - - USER_UID=1000 - - USER_GID=1000 - ``` - -- Mount `/home/git/.ssh` of the host into the container. This ensures that the `authorized_keys` file is shared between the host `git` user and the container `git` user otherwise the SSH authentication cannot work inside the container. - - ```yaml - volumes: - - /home/git/.ssh/:/data/git/.ssh - ``` - -- Now a SSH key pair needs to be created on the host. This key pair will be used to authenticate the `git` user on the host to the container. As an administrative user on the host run: (by administrative user we mean a user that can sudo to root) - - ```bash - sudo -u git ssh-keygen -t rsa -b 4096 -C "Gitea Host Key" - ``` - -- Please note depending on the local version of ssh you may want to consider using `-t ecdsa` here. - -- `/home/git/.ssh/authorized_keys` on the host now needs to be modified. It needs to act in the same way as `authorized_keys` within the Gitea container. Therefore add the public key of the key you created above ("Gitea Host Key") to `~/git/.ssh/authorized_keys`. As an administrative user on the host run: - - ```bash - sudo -u git cat /home/git/.ssh/id_rsa.pub | sudo -u git tee -a /home/git/.ssh/authorized_keys - sudo -u git chmod 600 /home/git/.ssh/authorized_keys - ``` - - Important: The pubkey from the `git` user needs to be added "as is" while all other pubkeys added via the Gitea web interface will be prefixed with `command="/usr [...]`. - - `/home/git/.ssh/authorized_keys` should then look somewhat like - - ```bash - # SSH pubkey from git user - ssh-rsa <Gitea Host Key> - - # other keys from users - command="/usr/local/bin/gitea --config=/data/gitea/conf/app.ini serv key-1",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty <user pubkey> - ``` - -- The next step is to create the fake host `gitea` command that will forward commands from the host to the container. The name of this file depends on your version of Gitea: - - - For Gitea v1.16.0+. As an administrative user on the host run: - - ```bash - cat <<"EOF" | sudo tee /usr/local/bin/gitea - #!/bin/sh - ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $0 $@" - EOF - sudo chmod +x /usr/local/bin/gitea - ``` - -Here is a detailed explanation what is happening when a SSH request is made: - -1. The client adds their SSH public key to Gitea using the webpage. -2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`. - - However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too. -3. This entry has the public key, but also has a `command=` option. - - This command matches the location of the Gitea binary on the container, but also the location of the shim on the host. -4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`. -5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host. -6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file. - - Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found -7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed. -8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=` -9. This means that the host runs the host `/usr/local/bin/gitea` shim that opens an SSH from the host to container passing the rest of the command arguments directly to `/usr/local/bin/gitea` on the container. -10. Meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands. - -**Notes** - -SSH container passthrough using `authorized_keys` will work only if - -- `opensshd` is used in the container -- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation -- `LOCAL_ROOT_URL` is not changed (depending on the changes) - -If you try to run `gitea` on the host, you will attempt to ssh to the container and thence run the `gitea` command there. - -Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface. - -### SSHing Shell (with authorized_keys) - -In this option, the idea is that the host simply uses the `authorized_keys` that gitea creates but at step 8 above we change the shell that the host runs to ssh directly into the docker and then run the shell there. This means that the `gitea` that is then run is the real docker `gitea`. - -- In this case we setup as per SSHing Shim except instead of creating `/usr/local/bin/gitea` -we create a new shell for the git user. As an administrative user on the host run: - - ```bash - cat <<"EOF" | sudo tee /home/git/ssh-shell - #!/bin/sh - shift - ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $@" - EOF - sudo chmod +x /home/git/ssh-shell - sudo usermod -s /home/git/ssh-shell git - ``` - - Be careful here - if you try to login as the git user in future you will ssh directly to the docker. - -Here is a detailed explanation what is happening when a SSH request is made: - -1. The client adds their SSH public key to Gitea using the webpage. -2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`. - - However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too. -3. This entry has the public key, but also has a `command=` option. - - This command matches the location of the Gitea binary on the container. -4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`. -5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host. -6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file. - - Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found -7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed. -8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=` -9. The shell of the host `git` user is now our `ssh-shell` which opens an SSH connection from the host to container, (which opens a shell on the container for the container `git`). -10. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands. - -**Notes** - -SSH container passthrough using `authorized_keys` will work only if - -- `opensshd` is used in the container -- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation -- `LOCAL_ROOT_URL` is not changed (depending on the changes) - -If you try to login as the `git` user on the host in future you will ssh directly to the docker. - -Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface. - -### Docker Shell (with authorized_keys) - -Similar to the above ssh shell technique we can use a shell which simply uses `docker exec`. As an administrative user on the host run: - -```bash -cat <<"EOF" | sudo tee /home/git/docker-shell -#!/bin/sh -/usr/bin/docker exec -i -u git --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@" -EOF -sudo chmod +x /home/git/docker-shell -sudo usermod -s /home/git/docker-shell git -``` - -Here is a detailed explanation what is happening when a SSH request is made: - -1. The client adds their SSH public key to Gitea using the webpage. -2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`. - - However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too. -3. This entry has the public key, but also has a `command=` option. - - This command matches the location of the Gitea binary on the container. -4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`. -5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host. -6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file. - - Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found -7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed. -8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=` -9. The shell of the host `git` user is now our `docker-shell` which uses `docker exec` to open a shell for the `git` user on the container. -10. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands. - -Note that `gitea` in the docker command above is the name of the container. If you named yours differently, don't forget to change that. The host `git` user also has to have -permission to run `docker exec`. - -**Notes** - -Docker shell passthrough using `authorized_keys` will work only if - -- `opensshd` is used in the container -- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation -- `LOCAL_ROOT_URL` is not changed (depending on the changes) - -If you try to login as the `git` user on the host in future you will `docker exec` directly to the docker. - -A Docker execing shim could be created similarly to above. - -### Docker Shell with AuthorizedKeysCommand - -The AuthorizedKeysCommand route provides another option that does not require many changes to the compose file or the `authorized_keys` - but does require changes to the host `/etc/sshd_config`. - -In this option, the idea is that the host SSH uses an `AuthorizedKeysCommand` instead of relying on sharing the `authorized_keys` file that gitea creates. We continue to use a special shell at step 8 above to exec into the docker and then run the shell there. This means that the `gitea` that is then run is the real docker `gitea`. - -- On the host create a `git` user with permission to run `docker exec`. -- We will again assume that the Gitea container is called `gitea`. -- Modify the `git` user's shell to forward commands to the `sh` executable inside the container using `docker exec`. As an administrative user on the host run: - - ```bash - cat <<"EOF" | sudo tee /home/git/docker-shell - #!/bin/sh - /usr/bin/docker exec -i -u git --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@" - EOF - sudo chmod +x /home/git/docker-shell - sudo usermod -s /home/git/docker-shell git - ``` - -Now all attempts to login as the `git` user on the host will be forwarded to the docker - including the `SSH_ORIGINAL_COMMAND`. We now need to set-up SSH authentication on the host. - -We will do this by leveraging the [SSH AuthorizedKeysCommand](administration/command-line.md#keys) to match the keys against those accepted by Gitea. - -Add the following block to `/etc/ssh/sshd_config`, on the host: - -```bash -Match User git - AuthorizedKeysCommandUser git - AuthorizedKeysCommand /usr/bin/docker exec -i -u git gitea /usr/local/bin/gitea keys -c /data/gitea/conf/app.ini -e git -u %u -t %t -k %k -``` - -(From 1.16.0 you will not need to set the `-c /data/gitea/conf/app.ini` option.) - -Finally restart the SSH server. As an administrative user on the host run: - -```bash -sudo systemctl restart sshd -``` - -Here is a detailed explanation what is happening when a SSH request is made: - -1. The client adds their SSH public key to Gitea using the webpage. -2. Gitea in the container will add an entry for this key to its database. -3. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`. -4. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host. -5. For each key the client provides, the host SSH server will checks its configuration for an `AuthorizedKeysCommand`. -6. The host runs the above `AuthorizedKeysCommand`, which execs in to the docker and then runs the `gitea keys` command. -7. Gitea on the docker will look in it's database to see if the public key matches and will return an entry like that of an `authorized_keys` command. -8. This entry has the public key, but also has a `command=` option which matches the location of the Gitea binary on the container. -9. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`. -10. The shell of the host `git` user is now our `docker-shell` which uses `docker exec` to open a shell for the `git` user on the container. -11. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands. - -**Notes** - -Docker shell passthrough using `AuthorizedKeysCommand` will work only if - -- The host `git` user is allowed to run the `docker exec` command. - -If you try to login as the `git` user on the host in future you will `docker exec` directly to the docker. - -A Docker execing shim could be created similarly to above. - -### SSH Shell with AuthorizedKeysCommand - -Create a key for the host `git` user as above, add it to the docker `/data/git/.ssh/authorized_keys` then finally create and set the `ssh-shell` as above. - -Add the following block to `/etc/ssh/sshd_config`, on the host: - -```bash -Match User git - AuthorizedKeysCommandUser git - AuthorizedKeysCommand /usr/bin/ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 /usr/local/bin/gitea keys -c /data/gitea/conf/app.ini -e git -u %u -t %t -k %k -``` - -(From 1.16.0 you will not need to set the `-c /data/gitea/conf/app.ini` option.) - -Finally restart the SSH server. As an administrative user on the host run: - -```bash -sudo systemctl restart sshd -``` - -Here is a detailed explanation what is happening when a SSH request is made: - -1. The client adds their SSH public key to Gitea using the webpage. -2. Gitea in the container will add an entry for this key to its database. -3. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`. -4. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host. -5. For each key the client provides, the host SSH server will checks its configuration for an `AuthorizedKeysCommand`. -6. The host runs the above `AuthorizedKeysCommand`, which will SSH in to the docker and then run the `gitea keys` command. -7. Gitea on the docker will look in it's database to see if the public key matches and will return an entry like that of an `authorized_keys` command. -8. This entry has the public key, but also has a `command=` option which matches the location of the Gitea binary on the container. -9. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`. -10. The shell of the host `git` user is now our `git-shell` which uses SSH to open a shell for the `git` user on the container. -11. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands. - -**Notes** - -SSH container passthrough using `AuthorizedKeysCommand` will work only if - -- `opensshd` is running on the container - -If you try to login as the `git` user on the host in future you will `ssh` directly to the docker. - -Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface. - -SSHing shims could be created similarly to above. diff --git a/docs/content/installation/with-docker.zh-cn.md b/docs/content/installation/with-docker.zh-cn.md deleted file mode 100644 index fcaff1c119..0000000000 --- a/docs/content/installation/with-docker.zh-cn.md +++ /dev/null @@ -1,380 +0,0 @@ ---- -date: "2016-12-01T16:00:00+02:00" -title: "使用 Docker 安装" -slug: "install-with-docker" -sidebar_position: 70 -toc: false -draft: false -aliases: - - /zh-cn/install-with-docker -menu: - sidebar: - parent: "installation" - name: "使用 Docker 安装" - sidebar_position: 70 - identifier: "install-with-docker" ---- - -# 使用 Docker 安装 - -Gitea 在其 Docker Hub 组织内提供自动更新的 Docker 镜像。可以始终使用最新的稳定标签或使用其他服务来更新 Docker 镜像。 - -该参考设置指导用户完成基于 `docker-compose` 的设置，但是 `docker-compose` 的安装不在本文档的范围之内。要安装 `docker-compose` 本身，请遵循官方[安装说明](https://docs.docker.com/compose/install/)。 - -## 基本 - -最简单的设置只是创建一个卷和一个网络，然后将 `gitea/gitea:latest` 镜像作为服务启动。由于没有可用的数据库，因此可以使用 SQLite3 初始化数据库。创建一个类似 `gitea` 的目录，并将以下内容粘贴到名为 `docker-compose.yml` 的文件中。请注意，该卷应由配置文件中指定的 UID/GID 的用户/组拥有。如果您不授予卷正确的权限，则容器可能无法启动。另请注意，标签 `:latest` 将安装当前的开发版本。对于稳定的发行版，您可以使用 `:1` 或指定某个发行版，例如 `@version@`。 - -```yaml -version: "3" - -networks: - gitea: - external: false - -services: - server: - image: gitea/gitea:@version@ - container_name: gitea - environment: - - USER_UID=1000 - - USER_GID=1000 - restart: always - networks: - - gitea - volumes: - - ./gitea:/data - - /etc/timezone:/etc/timezone:ro - - /etc/localtime:/etc/localtime:ro - ports: - - "3000:3000" - - "222:22" -``` - -## 端口 - -要将集成的 openSSH 守护进程和 Web 服务器绑定到其他端口，请调整端口部分。通常，只需更改主机端口，容器内的端口保持原样即可。 - -```diff -version: "3" - -networks: - gitea: - external: false - -services: - server: - image: gitea/gitea:@version@ - container_name: gitea - environment: - - USER_UID=1000 - - USER_GID=1000 - restart: always - networks: - - gitea - volumes: - - ./gitea:/data - - /etc/timezone:/etc/timezone:ro - - /etc/localtime:/etc/localtime:ro - ports: -- - "3000:3000" -- - "222:22" -+ - "8080:3000" -+ - "2221:22" -``` - -## 数据库 - -### MySQL 数据库 - -要将 Gitea 与 MySQL 数据库结合使用，请将这些更改应用于上面创建的 `docker-compose.yml` 文件。 - -```diff -version: "3" - -networks: - gitea: - external: false - -services: - server: - image: gitea/gitea:@version@ - container_name: gitea - environment: - - USER_UID=1000 - - USER_GID=1000 -+ - GITEA__database__DB_TYPE=mysql -+ - GITEA__database__HOST=db:3306 -+ - GITEA__database__NAME=gitea -+ - GITEA__database__USER=gitea -+ - GITEA__database__PASSWD=gitea - restart: always - networks: - - gitea - volumes: - - ./gitea:/data - - /etc/timezone:/etc/timezone:ro - - /etc/localtime:/etc/localtime:ro - ports: - - "3000:3000" - - "222:22" -+ depends_on: -+ - db -+ -+ db: -+ image: mysql:8 -+ restart: always -+ environment: -+ - MYSQL_ROOT_PASSWORD=gitea -+ - MYSQL_USER=gitea -+ - MYSQL_PASSWORD=gitea -+ - MYSQL_DATABASE=gitea -+ networks: -+ - gitea -+ volumes: -+ - ./mysql:/var/lib/mysql -``` - -### PostgreSQL 数据库 - -要将 Gitea 与 PostgreSQL 数据库结合使用，请将这些更改应用于上面创建的 `docker-compose.yml` 文件。 - -```diff -version: "3" - -networks: - gitea: - external: false - -services: - server: - image: gitea/gitea:@version@ - container_name: gitea - environment: - - USER_UID=1000 - - USER_GID=1000 -+ - GITEA__database__DB_TYPE=postgres -+ - GITEA__database__HOST=db:5432 -+ - GITEA__database__NAME=gitea -+ - GITEA__database__USER=gitea -+ - GITEA__database__PASSWD=gitea - restart: always - networks: - - gitea - volumes: - - ./gitea:/data - - /etc/timezone:/etc/timezone:ro - - /etc/localtime:/etc/localtime:ro - ports: - - "3000:3000" - - "222:22" -+ depends_on: -+ - db -+ -+ db: -+ image: postgres:14 -+ restart: always -+ environment: -+ - POSTGRES_USER=gitea -+ - POSTGRES_PASSWORD=gitea -+ - POSTGRES_DB=gitea -+ networks: -+ - gitea -+ volumes: -+ - ./postgres:/var/lib/postgresql/data -``` - -## 命名卷 - -要使用命名卷而不是主机卷，请在 `docker-compose.yml` 配置中定义并使用命名卷。此更改将自动创建所需的卷。您无需担心命名卷的权限；Docker 将自动处理该问题。 - -```diff -version: "3" - -networks: - gitea: - external: false - -+volumes: -+ gitea: -+ driver: local -+ -services: - server: - image: gitea/gitea:@version@ - container_name: gitea - restart: always - networks: - - gitea - volumes: -- - ./gitea:/data -+ - gitea:/data - - /etc/timezone:/etc/timezone:ro - - /etc/localtime:/etc/localtime:ro - ports: - - "3000:3000" - - "222:22" -``` - -MySQL 或 PostgreSQL 容器将需要分别创建。 - -## 启动 - -要基于 `docker-compose` 启动此设置，请执行 `docker-compose up -d`，以在后台启动 Gitea。使用 `docker-compose ps` 将显示 Gitea 是否正确启动。可以使用 `docker-compose logs` 查看日志。 - -要关闭设置，请执行 `docker-compose down`。这将停止并杀死容器。这些卷将仍然存在。 - -注意：如果在 http 上使用非 3000 端口，请更改 app.ini 以匹配 `LOCAL_ROOT_URL = http://localhost:3000/`。 - -## 安装 - -通过 `docker-compose` 启动 Docker 安装后，应该可以使用喜欢的浏览器访问 Gitea，以完成安装。访问 http://server-ip:3000 并遵循安装向导。如果数据库是通过上述 `docker-compose` 设置启动的，请注意，必须将 `db` 用作数据库主机名。 - -## 环境变量 - -您可以通过环境变量配置 Gitea 的一些设置： - -（默认值以**粗体**显示） - -- `APP_NAME`：**“Gitea: Git with a cup of tea”**：应用程序名称，在页面标题中使用。 -- `RUN_MODE`：**prod**：应用程序运行模式，会影响性能和调试。"dev"，"prod"或"test"。 -- `DOMAIN`：**localhost**：此服务器的域名，用于 Gitea UI 中显示的 http 克隆 URL。 -- `SSH_DOMAIN`：**localhost**：该服务器的域名，用于 Gitea UI 中显示的 ssh 克隆 URL。如果启用了安装页面，则 SSH 域服务器将采用以下形式的 DOMAIN 值（保存时将覆盖此设置）。 -- `SSH_PORT`：**22**：克隆 URL 中显示的 SSH 端口。 -- `SSH_LISTEN_PORT`：**%(SSH_PORT)s**：内置 SSH 服务器的端口。 -- `DISABLE_SSH`：**false**：如果不可用，请禁用 SSH 功能。如果要禁用 SSH 功能，则在安装 Gitea 时应将 SSH 端口设置为 `0`。 -- `HTTP_PORT`：**3000**：HTTP 监听端口。 -- `ROOT_URL`：**""**：覆盖自动生成的公共 URL。如果内部 URL 和外部 URL 不匹配（例如在 Docker 中），这很有用。 -- `LFS_START_SERVER`：**false**：启用 git-lfs 支持。 -- `DB_TYPE`：**sqlite3**：正在使用的数据库类型[mysql，postgres，mssql，sqlite3]。 -- `DB_HOST`：**localhost:3306**：数据库主机地址和端口。 -- `DB_NAME`：**gitea**：数据库名称。 -- `DB_USER`：**root**：数据库用户名。 -- `DB_PASSWD`：**"_empty_"** ：数据库用户密码。如果您在密码中使用特殊字符，请使用“您的密码”进行引用。 -- `INSTALL_LOCK`：**false**：禁止访问安装页面。 -- `SECRET_KEY`：**""** ：全局密钥。这应该更改。如果它具有一个值并且 `INSTALL_LOCK` 为空，则 `INSTALL_LOCK` 将自动设置为 `true`。 -- `DISABLE_REGISTRATION`：**false**：禁用注册，之后只有管理员才能为用户创建帐户。 -- `REQUIRE_SIGNIN_VIEW`：**false**：启用此选项可强制用户登录以查看任何页面。 -- `USER_UID`：**1000**：在容器内运行 Gitea 的用户的 UID（Unix 用户 ID）。如果使用主机卷，则将其与 `/data` 卷的所有者的 UID 匹配（对于命名卷，则不需要这样做）。 -- `USER_GID`：**1000**：在容器内运行 Gitea 的用户的 GID（Unix 组 ID）。如果使用主机卷，则将其与 `/data` 卷的所有者的 GID 匹配（对于命名卷，则不需要这样做）。 - -## 自定义 - -[此处](administration/customizing-gitea.md)描述的定制文件应放在 `/data/gitea` 目录中。如果使用主机卷，则访问这些文件非常容易；对于命名卷，可以通过另一个容器或通过直接访问 `/var/lib/docker/volumes/gitea_gitea/_data` 来完成。安装后，配置文件将保存在 `/data/gitea/conf/app.ini` 中。 - -## 升级 - -:exclamation::exclamation: **确保已将数据卷到 Docker 容器外部的某个位置** :exclamation::exclamation: - -要将安装升级到最新版本： - -```bash -# Edit `docker-compose.yml` to update the version, if you have one specified -# Pull new images -docker-compose pull -# Start a new container, automatically removes old one -docker-compose up -d -``` - -## 使用环境变量管理部署 - -除了上面的环境变量之外，`app.ini` 中的任何设置都可以使用以下形式的环境变量进行设置或覆盖：`GITEA__SECTION_NAME__KEY_NAME`。 每次 docker 容器启动时都会应用这些设置。 完整信息在[这里](https://github.com/go-gitea/gitea/tree/master/contrib/environment-to-ini)。 - -```bash -... -services: - server: - environment: - - GITEA__mailer__ENABLED=true - - GITEA__mailer__FROM=${GITEA__mailer__FROM:?GITEA__mailer__FROM not set} - - GITEA__mailer__PROTOCOL=smtps - - GITEA__mailer__HOST=${GITEA__mailer__HOST:?GITEA__mailer__HOST not set} - - GITEA__mailer__USER=${GITEA__mailer__USER:-apikey} - - GITEA__mailer__PASSWD="""${GITEA__mailer__PASSWD:?GITEA__mailer__PASSWD not set}""" -``` - -Gitea 将为每次新安装自动生成新的 `SECRET_KEY` 并将它们写入 `app.ini`。 如果您想手动设置 `SECRET_KEY`，您可以使用以下 docker 命令来使用 Gitea 内置的[方法](administration/command-line.md#generate)生成 `SECRET_KEY`。 安装后请妥善保管您的 `SECRET_KEY`，如若丢失则无法解密已加密的数据。 - -以下命令将向 `stdout` 输出一个新的 `SECRET_KEY` 和 `INTERNAL_TOKEN`，然后您可以将其放入环境变量中。 - -```bash -docker run -it --rm gitea/gitea:1 gitea generate secret SECRET_KEY -docker run -it --rm gitea/gitea:1 gitea generate secret INTERNAL_TOKEN -``` - -```yaml -... -services: - server: - environment: - - GITEA__security__SECRET_KEY=[value returned by generate secret SECRET_KEY] - - GITEA__security__INTERNAL_TOKEN=[value returned by generate secret INTERNAL_TOKEN] -``` - -## SSH 容器直通 - -由于 SSH 在容器内运行，因此，如果需要 SSH 支持，则需要将 SSH 从主机传递到容器。一种选择是在非标准端口上运行容器 SSH（或将主机端口移至非标准端口）。另一个可能更直接的选择是将 SSH 连接从主机转发到容器。下面将说明此设置。 - -本指南假定您已经在名为 `git` 的主机上创建了一个用户，该用户与容器值 `USER_UID`/`USER_GID` 共享相同的 `UID`/`GID`。这些值可以在 `docker-compose.yml` 中设置为环境变量： - -```bash -environment: - - USER_UID=1000 - - USER_GID=1000 -``` - -接下来将主机的 `/home/git/.ssh` 装入容器。否则，SSH 身份验证将无法在容器内运行。 - -```bash -volumes: - - /home/git/.ssh/:/data/git/.ssh -``` - -现在，需要在主机上创建 SSH 密钥对。该密钥对将用于向主机验证主机上的 `git` 用户。 - -```bash -sudo -u git ssh-keygen -t rsa -b 4096 -C "Gitea Host Key" -``` - -在下一步中，需要在主机上创建一个名为 `/usr/local/bin/gitea` 的文件（具有可执行权限）。该文件将发出从主机到容器的 SSH 转发。将以下内容添加到 `/usr/local/bin/gitea`： - -```bash -ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $0 $@" -``` - -为了使转发正常工作，需要将容器（22）的 SSH 端口映射到 `docker-compose.yml` 中的主机端口 2222。由于此端口不需要暴露给外界，因此可以将其映射到主机的 `localhost`： - -```bash -ports: - # [...] - - "127.0.0.1:2222:22" -``` - -另外，主机上的 `/home/git/.ssh/authorized_keys` 需要修改。它需要以与 Gitea 容器内的 `authorized_keys` 相同的方式进行操作。因此，将您在上面创建的密钥（“Gitea 主机密钥”）的公共密钥添加到 `~/git/.ssh/authorized_keys`。这可以通过 `echo "$(cat /home/git/.ssh/id_rsa.pub)" >> /home/git/.ssh/authorized_keys` 完成。重要提示：来自 `git` 用户的公钥需要“按原样”添加，而通过 Gitea 网络界面添加的所有其他公钥将以 `command="/app [...]` 作为前缀。 - -该文件应该看起来像： - -```bash -# SSH pubkey from git user -ssh-rsa <Gitea Host Key> - -# other keys from users -command="/usr/local/bin/gitea --config=/data/gitea/conf/app.ini serv key-1",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty <user pubkey> -``` - -这是详细的说明，当发出 SSH 请求时会发生什么： - -1. 使用 `git` 用户向主机发出 SSH 请求，例如 `git clone git@domain:user/repo.git`。 -2. 在 `/home/git/.ssh/authorized_keys` 中，该命令执行 `/usr/local/bin/gitea` 脚本。 -3. `/usr/local/bin/gitea` 将 SSH 请求转发到端口 2222，该端口已映射到容器的 SSH 端口（22）。 -4. 由于 `/home/git/.ssh/authorized_keys` 中存在 `git` 用户的公钥，因此身份验证主机 → 容器成功，并且 SSH 请求转发到在 docker 容器中运行的 Gitea。 - -如果在 Gitea Web 界面中添加了新的 SSH 密钥，它将以与现有密钥相同的方式附加到 `.ssh/authorized_keys` 中。 - -**注意** - -SSH 容器直通仅在以下情况下有效 - -- 在容器中使用 `opensshd` -- 如果未将 `AuthorizedKeysCommand` 与 `SSH_CREATE_AUTHORIZED_KEYS_FILE = false` 结合使用以禁用授权文件密钥生成 -- `LOCAL_ROOT_URL` 不变 |