网站导航
> 技术文档 > @Gitea 介绍&部署&使用详细指南_gitea 管理员账号

@Gitea 介绍&部署&使用详细指南_gitea 管理员账号

网友: 技术文档 2025-09-02 19:17:18

文章目录

    • **Gitea 介绍、部署、使用详细指南**
    • 1. 概述
      • 1.1 什么是 Gitea？
      • 1.2 核心特性
      • 1.3 Gitea vs GitLab vs Gogs
    • 2. 部署指南
      • 2.1 前提条件
      • 2.2 部署方法一：使用 Docker Compose (推荐)
      • 2.3 部署方法二：二进制安装
      • 2.4 配置反向代理 (Nginx) 和 SSL (可选但推荐)
    • 3. 基本使用指南
      • 3.1 初始设置
      • 3.2 用户与权限管理
      • 3.3 协作功能
    • 4. 常见问题 (FAQ)
    • 附录

Gitea 介绍、部署、使用详细指南

1. 概述

1.1 什么是 Gitea？

Gitea 是一个用 Go 语言编写的、轻量级、开源、自托管的 Git 服务平台。它被设计成可以以最低的资源开销在几乎任何能够运行 Go 语言的平台上运行，包括 Raspberry Pi 等边缘设备。它是 Gogs 的一个分支，但由一个更活跃的社区驱动和维护。

1.2 核心特性

  • Git 托管: 提供完整的 Git 服务，支持 SSH, HTTP 和 HTTPS 协议。
  • Web 界面: 直观友好的 Web 用户界面，与 GitHub 和 GitLab 类似。
  • 代码审查: 支持 Pull Requests (合并请求) 和代码行注释。
  • 问题跟踪 (Issues): 内置的问题和任务跟踪系统。
  • Wiki: 为每个仓库提供独立的 Wiki 文档系统。
  • CI/CD 集成: 可以通过 Webhook 轻松集成 Drone, Jenkins 等 CI/CD 工具。
  • 多语言支持: 支持多种界面语言。
  • 轻量高效: 二进制文件部署，内存和 CPU 占用极低。
  • 多数据库支持: 支持 SQLite, PostgreSQL, MySQL 和 MariaDB。

1.3 Gitea vs GitLab vs Gogs

  • vs GitLab: GitLab 功能极其强大（内置CI/CD，容器仓库等），但也因此非常重量级，对服务器资源（尤其是内存）要求高。Gitea 是轻量级替代方案，专注于核心的代码托管功能。
  • vs Gogs: Gitea 是 Gogs 的分支。主要区别在于社区治理模式，Gitea 拥有一个更开放和活跃的社区，因此功能更新和迭代速度更快。

2. 部署指南

本文将以最常用且易于维护的 Docker Compose 方式在 Linux 服务器上部署 Gitea。同时也会简要介绍二进制包部署。

2.1 前提条件

  • 一台运行中的 Linux 服务器 (如 Ubuntu 20.04/22.04, CentOS 7/8)
  • Docker 和 Docker Compose 已安装
  • 域名一枚 (可选，但强烈推荐)，并解析到你的服务器 IP

2.2 部署方法一：使用 Docker Compose (推荐)

这种方法将所有服务（Gitea, PostgreSQL, Redis）容器化，管理方便，隔离性好。

步骤 1: 创建项目目录结构

sudo mkdir -p /opt/gitea/{data,postgres,redis}cd /opt/gitea
  • data: 用于挂载 Gitea 的主目录（仓库、配置、日志等）
  • postgres: 用于挂载数据库数据，避免容器销毁后数据丢失
  • redis: 用于挂载 Redis 数据

步骤 2: 创建 docker-compose.yml 文件
使用你喜欢的编辑器（如 vim 或 nano) 创建文件 docker-compose.yml:

version: \'3\'networks: gitea: external: falseservices: server: image: gitea/gitea:latest container_name: gitea_server 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=your_secure_password_here restart: always networks: - gitea volumes: - ./data:/data - /etc/timezone:/etc/timezone:ro - /etc/localtime:/etc/localtime:ro ports: - \"3000:3000\" - \"2222:22\" depends_on: - db - redis db: image: postgres:15 container_name: gitea_db environment: - POSTGRES_USER=gitea - POSTGRES_PASSWORD=your_secure_password_here - POSTGRES_DB=gitea restart: always networks: - gitea volumes: - ./postgres:/var/lib/postgresql/data redis: image: redis:9-alpine container_name: gitea_redis restart: always networks: - gitea volumes: - ./redis:/data command: \"redis-server --appendonly yes\"

重要提示: 请将 your_secure_password_here 替换为一个强密码。

步骤 3: 启动 Gitea 栈

sudo docker-compose up -d

-d 选项表示在后台运行。

步骤 4: 完成安装向导
访问 http://your_server_ip:3000，你将看到 Gitea 的首次安装配置页面。

  • 数据库设置: 保持默认即可，Docker Compose 已经通过环境变量配置好了。
  • 常规设置:
    • 站点名称: 你的 Gitea 实例名称。
    • 仓库根目录: /data/git/repositories (容器内路径，已挂载，勿改)。
    • LFS 根目录: /data/git/lfs (同上)。
    • SSH 服务器端口: 填写 2222（与 docker-compose.yml 中映射的端口一致）。
    • SSH 服务器域名: 填写你的服务器 IP 或域名。
    • Gitea 基本 URL: 填写 http://your_domain_or_ip:3000/ 或如果你配置了反向代理，则填写 https://your_domain.com/。
  • 创建第一个管理员账户。

配置完成后，点击“安装 Gitea”。

2.3 部署方法二：二进制安装

适用于无法使用 Docker 的环境。

  1. 从 Gitea 下载页面 下载适用于你架构的二进制文件。
  2. 赋予执行权限并移动到系统路径： 
    wget -O gitea https://dl.gitea.com/gitea/1.20.0/gitea-1.20.0-linux-amd64chmod +x giteasudo mv gitea /usr/local/bin/
  3. 创建系统用户并设置目录权限： 
    sudo adduser --system --shell /bin/bash --group --disabled-password --home /home/git gitsudo mkdir -p /var/lib/gitea/{custom,data,log}sudo chown -R git:git /var/lib/giteasudo chmod -R 750 /var/lib/gitea
  4. 配置 Gitea 为系统服务 (/etc/systemd/system/gitea.service)： 
    [Unit]Description=GiteaAfter=syslog.targetAfter=network.target[Service]RestartSec=2sType=simpleUser=gitGroup=gitWorkingDirectory=/var/lib/giteaExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.iniRestart=always[Install]WantedBy=multi-user.target
  5. 启动并启用服务： 
    sudo systemctl enable --now gitea
  6. 访问 http://your_server_ip:3000 完成网页安装向导。

2.4 配置反向代理 (Nginx) 和 SSL (可选但推荐)

目的: 使用域名访问并启用 HTTPS 加密。

  1. 安装 Nginx 和 Certbot：

    # Ubuntu/Debiansudo apt install nginx certbot python3-certbot-nginx# CentOS/Rocky Linuxsudo dnf install nginx certbot python3-certbot-nginx

  2. 创建 Nginx 配置文件 /etc/nginx/conf.d/gitea.conf：

    server { listen 80; server_name your_domain.com; location / { proxy_pass http://localhost:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; }}

  3. 测试配置并重载 Nginx：

    sudo nginx -tsudo systemctl reload nginx

  4. 使用 Certbot 获取 SSL 证书：

    sudo certbot --nginx -d your_domain.com

    Certbot 会自动修改 Nginx 配置，将其重定向到 HTTPS。

  5. 修改 Gitea 配置：更新 app.ini (对于 Docker，文件在 /opt/gitea/data/gitea/conf/app.ini) 中的 ROOT_URL：

    [server]ROOT_URL = https://your_domain.com/

  6. 重启 Gitea 服务或容器：

    # Docker Composesudo docker-compose restart# Systemdsudo systemctl restart gitea

现在你可以通过 https://your_domain.com 安全地访问 Gitea。

3. 基本使用指南

3.1 初始设置

  1. 注册与登录: 安装后，用创建的管理员账户登录。
  2. 创建仓库: 点击右上角 “+” 号 -> “新建仓库”。
  3. 推送到仓库: 
    echo \"# My Project\" >> README.mdgit initgit add README.mdgit commit -m \"first commit\"git branch -M maingit remote add origin https://your_domain.com/username/repo-name.gitgit push -u origin main

3.2 用户与权限管理

  • 管理员: 可以管理全站设置、用户、仓库、组织。
  • 用户: 可以创建仓库、加入组织、协作。
  • 组织: 用于管理团队和团队项目。可以创建团队并设置精细的仓库权限（读、写、管理员）。

3.3 协作功能

  • Fork & Pull Request: 工作流与 GitHub 完全一致。
  • 问题 (Issues): 可以分配、标签、里程碑管理。
  • Web 钩子 (Webhooks): 在仓库设置中配置，用于触发 CI/CD pipeline。

4. 常见问题 (FAQ)

Q1: 如何备份和恢复 Gitea？
A: Gitea 提供了方便的 CLI 命令（即使在 Docker 中也可使用）。

  • 备份: 
    # Docker 方式sudo docker exec -u git -it gitea_server bash -c \'/app/gitea/gitea dump -c /data/gitea/conf/app.ini\'# 备份文件会生成在 /opt/gitea/data/gitea/ 下，请将其拷贝到安全的地方。
  • 恢复:
    1. 停止 Gitea 服务。
    2. 使用 gitea restore 命令指定备份文件。
    3. 重启服务。

Q2: 如何升级 Gitea (Docker 方式)？
A: 非常简单！

cd /opt/giteasudo docker-compose pull # 拉取最新镜像sudo docker-compose down # 停止当前服务sudo docker-compose up -d # 用新镜像重新启动服务

Q3: 忘记管理员密码怎么办？
A: 可以通过命令行重置。

# Docker 方式sudo docker exec -it gitea_server bashsu gitcd /app/gitea./gitea admin user change-password --username your_admin_username --password your_new_password

Q4: 如何修改配置？
A: 主配置文件是 app.ini。

  • Docker: 位于挂载卷中，例如 /opt/gitea/data/gitea/conf/app.ini。修改后需要重启容器：sudo docker-compose restart。
  • 二进制: 通常位于 /etc/gitea/app.ini。修改后需要重启服务：sudo systemctl restart gitea。

Q5: 如何迁移旧服务器上的 Git 仓库到 Gitea？
A: 最简单的方法是：

  1. 在旧服务器上为每个仓库创建一个裸克隆：git clone --bare repo_url.git
  2. 在 Gitea 上创建一个新的空仓库。
  3. 将裸克隆推送到 Gitea： 
    cd repo.gitgit push --mirror https://gitea_url/username/new_repo.git

Q6: 出现 500 Internal Server Error 怎么办？
A:

  1. 首先查看日志定位错误原因。
    • Docker: sudo docker-compose logs server
    • 二进制: journalctl -u gitea -f 或查看 /var/lib/gitea/log/gitea.log
  2. 常见原因：数据库连接失败、权限问题、配置文件格式错误。

附录

  • 官方文档: https://docs.gitea.com
  • GitHub 仓库: https://github.com/go-gitea/gitea
  • 论坛和社区: https://discourse.gitea.com
网络标签：

相关问题