Gitea 完整安装与自启配置指南

1. 系统环境准备

# 更新系统并安装基础依赖（以 Ubuntu/Debian 为例）
sudo apt update && sudo apt upgrade -y
sudo apt install git sqlite3 curl -y

2. 创建专用运行用户

# 创建一个名为 gitea 的系统用户，用于安全地运行服务
sudo adduser --system --shell /bin/bash --gecos 'Git Version Control' --group --disabled-password --home /home/gitea gitea

3. 下载并安装 Gitea 二进制文件

# 下载最新版本（请根据官方最新页面替换版本号）
wget -O gitea https://dl.gitea.com/gitea/1.23.1/gitea-1.23.1-linux-amd64

# 赋予执行权限并移动到全局可执行目录
chmod +x gitea
sudo mv gitea /usr/local/bin/gitea

# 验证安装是否成功
gitea --version

4. 创建必要的目录结构

# 创建工作数据、自定义配置和日志目录
sudo mkdir -p /var/lib/gitea/{custom,data,log}
sudo chown -R gitea:gitea /var/lib/gitea/
sudo chmod -R 750 /var/lib/gitea/

# 创建应用配置文件目录（交由 root 管理，防止普通用户篡改）
sudo mkdir -p /etc/gitea
sudo chown root:gitea /etc/gitea
sudo chmod 770 /etc/gitea

5. 配置 Systemd 自启动服务

创建服务配置文件：

sudo nano /etc/systemd/system/gitea.service

将以下内容粘贴到文件中：

[Unit]
Description=Gitea (Git with a cup of tea)
After=syslog.target network.target

[Service]
RestartSec=2s
Type=simple
User=gitea
Group=gitea
WorkingDirectory=/var/lib/gitea/
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Restart=always
Environment=USER=gitea GITEA_WORK_DIR=/var/lib/gitea

[Install]
WantedBy=multi-user.target

6. 启动服务并设置开机自启

# 重新加载 systemd 配置
sudo systemctl daemon-reload

# 启用开机自启并立即启动 Gitea
sudo systemctl enable --now gitea

# 查看运行状态
sudo systemctl status gitea

7. 防火墙放行端口

Gitea 默认 Web 端口为 3000，需在防火墙中放行：

# 如果使用 UFW 防火墙
sudo ufw allow 3000/tcp
sudo ufw enable

8. Web 界面初始化配置

在浏览器中访问 http://<你的服务器IP>:3000，首次进入会自动跳转到安装向导：

  1. 数据库设置：个人使用可选择默认的 SQLite3；团队使用建议提前配置好 MySQL 或 PostgreSQL。
  2. 一般设置：填写站点名称、仓库根目录（保持默认 /var/lib/gitea/data/gitea-repositories 即可）。
  3. 管理员账号设置：在此处设置管理员用户名、邮箱和密码。
  4. 点击“立即安装”，等待初始化完成即可使用。

📁 目录结构总览

/
├── etc/
│   ├── systemd/system/
│   │   └── gitea.service            # [服务配置] 定义启动参数、依赖及运行用户
│   └── gitea/
│       └── app.ini                  # [应用配置] 数据库、端口、站点名称等核心设置
├── usr/local/bin/
│   └── gitea                        # [程序本体] Gitea 可执行文件 (二进制)
├── var/lib/gitea/                   # [工作目录] 运行时数据与持久化存储
│   ├── data/                        # —— 仓库数据、头像、附件等
│   ├── custom/                      # —— 自定义模板、配置文件覆盖
│   └── log/                         # —— 运行日志文件
└── home/git/                        # [用户目录] Git 全局配置 (.gitconfig)

📝 路径详细说明

路径类型作用与存放逻辑
/etc/systemd/system/gitea.service服务配置系统管理层：告诉 systemd 如何启动 Gitea，包含 ExecStart、User、Environment 等指令。优先级最高，确保服务安全可控。
/etc/gitea/app.ini应用配置配置管理层：存放 Gitea 运行参数。遵循 FHS 规范，配置与程序分离，便于备份、迁移及权限控制（通常属主为 root:git）。
/usr/local/bin/gitea可执行文件程序安装层：存放手动安装的第三方二进制文件。放在此处可确保全局环境变量 $PATH 可直接调用，且升级时仅需替换此文件。
/var/lib/gitea/数据目录数据存储层：存放 Git 仓库、数据库文件（若用 SQLite）、头像及日志。遵循“程序与数据分离”原则，防止升级覆盖数据，且便于独立备份。
/home/git/用户家目录环境兼容层：Git 工具默认读取 $HOME/.gitconfig。设置此路径是为了兼容 Git 命令行行为，确保 Gitea 内部调用 Git 时能正确读取全局配置。

架构设计核心原则

  1. 程序与数据分离：升级 Gitea 只需替换 /usr/local/bin/gitea，/var/lib/gitea 中的仓库数据完全不受影响。
  2. 配置集中管理：所有配置（系统级 systemd + 应用级 app.ini）均位于 /etc，符合 Linux 运维习惯，便于统一备份和审计。

  3. 权限最小化：

    • 程序文件：root:root (只读)
    • 配置文件：root:git (Git 用户只读，防止误改)
    • 数据目录：git:git (Git 用户读写)
  4. 环境隔离：通过 Environment=HOME=/home/git 在 systemd 中隔离环境变量，避免污染系统其他服务。<|im_article_end|>