## 一、项目介绍
Gitea 是一个用 Go 编写的、可自托管的“一体化软件开发服务平台”。官方 README 对其定位是：让搭建自托管 Git 服务的体验成为“最简单、最快、最无痛”的方式，功能涵盖 Git 托管、代码管理、代码审查、Issue 跟踪、项目看板、Wiki、团队协作、包仓库（Package Registry），以及可复用 GitHub Actions 工作流的 CI/CD 能力。
由于 Gitea 由 Go 编写，官方 README 明确说明它可运行在 Go 支持的所有平台与架构上，包括 Linux、macOS、FreeBSD/OpenBSD 与 Windows，覆盖 x86、amd64、ARM、RISC-V 64 与 PowerPC 架构。项目在 GitHub（go-gitea/gitea）持续活跃维护、保持高频版本发布，官方同时提供在线演示站 demo.gitea.com、免费云服务 gitea.com，以及 Docker 官方镜像 gitea/gitea（hub.docker.com/r/gitea/gitea），可直接在自有服务器上用容器部署。
## 二、功能拆解
按官方 README「Purpose」一节，Gitea 的核心功能如下：
Git 托管与代码管理：仓库、分支、标签、提交历史、文件浏览；
代码审查：Pull Request 流程，审查、评论、合并策略；
Issue 跟踪：问题、标签、里程碑管理；
项目看板：Kanban 式项目管理；
Wiki：内置项目文档空间；
团队协作：组织、团队、成员与权限管理；
包仓库 Package Registry：发布与拉取各类软件制品；
CI/CD：Gitea Actions，可复用 GitHub Actions 工作流。
## 三、官方/GitHub 链接
GitHub 仓库：https://github.com/go-gitea/gitea
官方文档：https://docs.gitea.com/
在线演示站：https://demo.gitea.com
Docker 官方镜像：https://hub.docker.com/r/gitea/gitea
官方论坛：https://forum.gitea.com/，Discord：https://discord.gg/Gitea
## 四、环境要求
官方《使用 Docker 安装》文档明确：本部署基于 docker-compose，因此前置要求是已安装 Docker 与 Docker Compose；docker-compose 本身的安装不属于 Gitea 文档范围，请按 Docker 官方说明安装（https://docs.docker.com/compose/install/）。
端口：官方示例默认映射 3000（Web）与 222（容器内 SSH 22 转发到宿主 222）；
数据目录：官方示例将宿主目录 ./gitea 挂载为容器内 /data（数据持久化）；数据库：官方默认使用 SQLite3（零依赖即可初始化）；官方文档同时给出 MySQL 8 与 PostgreSQL 14 的 compose 变体；
硬件：官方文档未给出最低硬件指标；占用取决于仓库数量与并发规模。
## 五、部署步骤
步骤 1：创建部署目录并进入
mkdir gitea && cd gitea
逐段解释：mkdir gitea 创建名为 gitea 的目录；&& 表示前一条成功后才执行下一条；cd gitea 进入该目录。后续 compose 文件与数据卷都放在这里。
预期输出参考：命令成功，无输出。
步骤 2：创建官方 docker-compose.yml
官方《使用 Docker 安装》「基本」一节的配置原文如下，将其粘贴到 docker-compose.yml 文件中：
version: "3"
networks:
gitea:
external: false
services:
server:
image: docker.gitea.com/gitea:latest
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"
逐段解释：version: "3" 声明 compose 文件版本；networks.gitea 定义一个名为 gitea 的内部网络；services.server 是唯一服务；image 使用官方镜像的最新稳定版（官方文档原文以 @dockerVersion@ 作为版本占位符，并注明 :latest 安装最新稳定版、:1 或具体版本号用于固定发行版、:main-nightly 为开发版；官方 README 亦提供 Docker Hub 官方镜像 gitea/gitea）；container_name: gitea 固定容器名；USER_UID=1000、USER_GID=1000 指定容器内运行 Gitea 的用户/组 ID，需与 /data 卷属主匹配（官方文档特别警告：卷权限不正确容器可能无法启动）；restart: always 容器异常退出或 Docker 重启后自动拉起；./gitea:/data 将宿主当前目录下的 gitea/ 挂载为容器数据目录；/etc/timezone、/etc/localtime 以只读方式传入时区；端口 3000（Web）与 222（SSH 22）。
步骤 3：后台启动
docker-compose up -d
逐段解释：docker-compose up 依据 docker-compose.yml 创建并启动容器；-d 表示后台（detached）运行。
预期输出参考：出现 Creating network "gitea_gitea" ...、Creating gitea ... done 之类的创建日志，最终回到命令行提示符。
步骤 4：确认启动状态
docker-compose ps
逐段解释：列出本 compose 项目的容器状态。Up 表示运行中。
预期输出参考：
Name Command State Ports
--------------------------------------------------------------------------
gitea /usr/bin/entrypoint ... Up 0.0.0.0:222->22/tcp, 0.0.0.0:3000->3000/tcp
步骤 5（可选）：查看运行日志
docker-compose logs -f
逐段解释：logs 输出容器日志，-f 持续跟踪。Ctrl+C 退出跟踪（不停止容器）。
预期输出参考：Gitea 启动日志（如 Starting new Gitea service ...、Listen: http://0.0.0.0:3000 等）。
## 六、配置参数详解
1. 配置文件位置：官方文档明确：“安装后，配置文件将保存在 /data/gitea/conf/app.ini 中”，即宿主目录 ./gitea/conf/app.ini。动态配置可在管理面板「配置」区修改；静态配置编辑 app.ini 后重启实例生效（官方 README FAQ）。
2. 官方环境变量（默认值以粗体表示）：
APP_NAME：默认 Gitea: Git with a cup of tea，应用名称，用于页面标题；
RUN_MODE：默认 prod，运行模式：dev / prod / test；
DOMAIN：默认 localhost，用于 UI 中 http 克隆 URL 的域名；
SSH_DOMAIN：默认 localhost，用于 ssh 克隆 URL 的域名；
SSH_PORT：默认 22，克隆 URL 中显示的 SSH 端口；
SSH_LISTEN_PORT：默认 %(SSH_PORT)s，内置 SSH 服务器监听端口；
DISABLE_SSH：默认 false，禁用 SSH 功能（如不可用）；
HTTP_PORT：默认 3000，HTTP 监听端口；
ROOT_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 为空时自动锁定安装页；
DISABLE_REGISTRATION：默认 false，禁用注册，之后仅管理员可创建账号；
REQUIRE_SIGNIN_VIEW：默认 false，强制登录后才能查看任何页面；
USER_UID：默认 1000，容器内运行用户 UID（主机卷时需与 /data 属主匹配）；
USER_GID：默认 1000，容器内运行用户 GID。
3. 通用覆盖语法 GITEA__SECTION__KEY：官方文档说明，app.ini 中任何设置都可用 GITEA__节名__键名 形式的环境变量设置或覆盖，每次容器启动时应用。官方示例：
environment:
- GITEA__mailer__ENABLED=true
- GITEA__mailer__PROTOCOL=smtps
- GITEA__mailer__HOST=${GITEA__mailer__HOST:?GITEA__mailer__HOST not set}
4. 数据库扩展：官方文档给出 MySQL 8（db:3306、MYSQL_ROOT_PASSWORD=gitea 等）与 PostgreSQL 14（db:5432、POSTGRES_PASSWORD=gitea 等）两种 compose 变体，需在 services 中增加 db 服务并给 server 增加 GITEA__database__DB_TYPE/HOST/NAME/USER/PASSWD 环境变量与 depends_on: - db。
5. 密钥生成（官方文档）：Gitea 每次新安装会自动生成新 SECRET_KEY 写入 app.ini；也可用官方命令手动生成：
docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret SECRET_KEY
docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret INTERNAL_TOKEN
逐段解释：docker run -it --rm 临时运行一次镜像；gitea generate secret SECRET_KEY 输出一个新的密钥到 stdout。官方文档警告：安装后请妥善保管 SECRET_KEY，丢失则无法解密已加密数据。
## 七、启动与运维
启动 / 停止：docker-compose up -d 启动；docker-compose down 停止并移除容器（官方原文：“这将停止并杀死容器。这些卷将仍然存在。”）。
查看状态 / 日志：docker-compose ps、docker-compose logs。
开机自启：官方 compose 配置中的 restart: always 即官方提供的自启方式，容器异常退出或 Docker 守护进程重启后自动恢复。
修改端口（官方「端口」一节）：只改主机侧端口，容器内端口保持原样：
ports:
- "8080:3000"
- "2221:22"
注意官方提示：“如果在 http 上使用非 3000 端口，请更改 app.ini 以匹配 LOCAL_ROOT_URL = http://localhost:3000/”，即需同时设置 GITEA__server__LOCAL_ROOT_URL 环境变量（或改 app.ini）为外部实际端口。
数据持久化：官方默认主机卷 ./gitea:/data；也可用官方「命名卷」写法 gitea:/data（在 compose 顶部声明 volumes: gitea: driver: local），命名卷权限由 Docker 自动处理。
SSH 容器直通：官方文档说明容器内 SSH 需从主机转发（主机 git 用户、/home/git/.ssh 挂载、/usr/local/bin/gitea 转发脚本、127.0.0.1:2222:22 映射），完整步骤见官方文档《SSH 容器直通》一节。
## 八、实操验证
1. 浏览器访问 http://服务器IP:3000，官方文档：“通过 docker-compose 启动 Docker 安装后……访问 http://server-ip:3000 并遵循安装向导”。
2. 安装向导中填写站点标题、管理员账号（用户名/邮箱/密码）、数据库类型（默认 SQLite3，路径自动初始化）。注意：官方文档提示，若数据库由上述 compose 的 db 服务提供，“必须将 db 用作数据库主机名”。
3. 安装完成后自动登录，点击右上角「＋」新建第一个仓库（New Repository），填写仓库名后创建。
4. 在本地验证克隆与推送：
git clone http://服务器IP:3000/用户名/仓库名.git
cd 仓库名 && echo hello > README.md && git add . && git commit -m init && git push
逐段解释：git clone 从 Gitea 拉取空仓库；随后创建 README、提交并推回。预期输出参考：clone 成功提示 Cloning into '仓库名'...，push 成功提示 * [new branch] main -> main 等 Git 常规输出。
## 登录与安全（重要）
官方默认账号密码：无默认账号。Gitea 没有出厂账号，安装向导的第一步就是创建管理员账号（用户名/邮箱/密码），该账号即第一个用户；此后普通用户可访问 http://服务器IP:3000/user/register 自行注册（若未设置 DISABLE_REGISTRATION）。
登录地址：http://服务器IP:3000/user/login。
首次登录修改密码：右上角头像，进入「设置」再点「账号」，可修改密码。
密码重置（管理员，官方命令行文档）：
docker exec -it gitea gitea admin user change-password --username 用户名 --password 新密码
逐段解释：docker exec -it gitea 进入运行中的 gitea 容器执行命令；gitea admin user change-password 是官方命令行工具；--username 与 --password 必填。官方文档示例：gitea admin user change-password --username myname --password asecurepassword。
密码配置存放位置：Gitea 不保存明文密码，密码以哈希形式存于数据库中（SQLite3 时为 /data/gitea/gitea.db，即宿主 ./gitea/gitea.db）；app.ini（/data/gitea/conf/app.ini）中存放 SECRET_KEY 等密钥配置，官方文档警告 SECRET_KEY 丢失将无法解密已加密数据。
安全提醒：部署完成后必须立即设置强密码管理员账号；公网部署时在安装向导中正确填写域名与 ROOT_URL，关注官方安全公告 https://github.com/go-gitea/gitea/security/advisories 与 Release 说明（官方 README FAQ）。
## 九、故障排查
案例 1：容器启动后立即退出，日志提示 /data 目录权限错误
报错原文（常见形式）：mkdir /data/gitea: permission denied 或 chown: changing ownership of '/data/gitea': Operation not permitted
报错原因：官方文档明确警告——“该卷应由配置文件中指定的 UID/GID 的用户/组拥有。如果您不授予卷正确的权限，则容器可能无法启动”（compose 中 USER_UID/USER_GID=1000，而宿主目录属主不是 1000）。
分步解决：1. docker-compose down 停止；2. 修正宿主数据目录属主：sudo chown -R 1000:1000 gitea；3. 重新 docker-compose up -d。或改用官方「命名卷」写法（gitea:/data），权限由 Docker 自动处理。
案例 2：仓库克隆地址显示 localhost，克隆失败
报错原文（常见形式）：fatal: unable to access 'http://localhost:3000/...': Could not resolve host: localhost
报错原因：官方环境变量表中 DOMAIN / SSH_DOMAIN 默认值为 localhost，ROOT_URL 为空，克隆 URL 按默认值生成。
分步解决：1. 安装向导中填写正确的域名（或 IP）与端口；2. 安装后如服务器地址变化，用环境变量覆盖（官方语法）：GITEA__server__DOMAIN=你的域名、GITEA__server__ROOT_URL=http://你的域名:端口/；3. docker-compose up -d 重启容器生效。
案例 3：修改 Web 端口后页面打不开或克隆地址错误
报错原因：官方文档明确提示——“如果在 http 上使用非 3000 端口，请更改 app.ini 以匹配 LOCAL_ROOT_URL = http://localhost:3000/”，即端口映射改了但内部 URL 未同步。
分步解决：1. compose 中改主机端口（如 8080:3000）；2. 增加环境变量 GITEA__server__LOCAL_ROOT_URL=http://localhost:8080/；3. 重启容器。
案例 4：SSH 克隆失败（Connection refused）
报错原因：容器内 SSH 需要官方「SSH 容器直通」配置（主机 git 用户、转发脚本、127.0.0.1:2222:22 映射、authorized_keys 处理），未配置则 22 端口不通。
分步解决：1. 按官方文档《SSH 容器直通》完整配置主机转发；2. 或改用 HTTP 克隆地址。官方文档注明该直通仅在容器使用 opensshd 等条件下有效。
## 十、升级、回滚与卸载
升级（官方文档「升级」一节）：
# 如有指定版本，编辑 docker-compose.yml 更新版本号
docker-compose pull
docker-compose up -d
逐段解释：docker-compose pull 拉取新镜像；docker-compose up -d 自动用新镜像重建容器。官方文档特别警告：升级前务必确保数据卷已挂载到容器外部（即 ./gitea:/data 形式），否则数据丢失。
回滚：官方未提供一键回滚命令；可将 docker-compose.yml 的 image 标签改回旧版本号（如 docker.gitea.com/gitea:1.27），再依次执行 docker-compose pull 与 docker-compose up -d。因数据卷保留在容器外，旧版本可正常读取数据（此操作基于官方镜像标签机制与数据卷保留特性）。
卸载：官方 docker-compose down 停止并移除容器（数据卷仍保留）。如需彻底清理：删除宿主数据目录 gitea/（即 /data 挂载点，此操作永久删除全部仓库数据，务必先备份，可 cp -r gitea /备份目录），并删除镜像：docker rmi docker.gitea.com/gitea:latest。
## 十一、商用许可合规说明
许可证：MIT License（官方 README 与仓库 LICENSE 文件明确）。
MIT 许可允许自由使用、修改、分发与商用（包括闭源商业产品），但必须保留原始版权声明与许可文本。
Gitea 由 go-gitea 社区维护；商用部署无需付费授权。官方同时提供 Gitea Cloud 托管与相关支持服务作为可选商业渠道（非强制项）。
|
评论交流