如何在 Linux 上轻量化部署 Gitea

我在上一篇文章中介绍过整体的同步思路 用 Gitea 打通 Windows 与 Linux 的笔记、代码同步，这一节分享部分具体方案：在 Linux 上完成 Gitea 的轻量化部署与基础配置。

Gitea 的适用场景：

• 本地统一管理代码与笔记，读写速度快
• 局域网内随时访问
• 对数据隐私与可控性有要求
• 需要托管大文件（支持 Git LFS）

需要说明的是，Gitea 的自动化能力不如 GitHub Actions，但如果你的核心诉求只是稳定、可控的版本管理，它已经足够好用。

注：Gitea 的发音是 /ˈɡɪtiːə/

1 部署和配置

1.1 使用 Docker Compose 部署

1. 创建目录 Gitea/，并添加 docker-compose.yml 文件：

version: "3"services:  server:    image: gitea/gitea:latest    container_name: gitea    restart: always    environment:      - USER_UID=1000      - USER_GID=1000    networks:      - gitea    volumes:      - ./gitea:/data      - /etc/timezone:/etc/timezone:ro      - /etc/localtime:/etc/localtime:ro    ports:      - "3000:3000"      - "222:22"networks:  gitea:    external: false

说明：

• ./gitea:/data
   把容器里的数据目录映射到宿主机。这样设置的好处是即使容器删掉重建，仓库、用户和配置也还在。
• Web 服务端口：3000（网页管理）： 3000 是网页访问端口，用来打开 Gitea 后台; 宿主机的 222 端口映射到容器内的 22 端口（Gitea 的 SSH 服务跑在容器里的 22）。
• YAML 对缩进要求很高。少空格或多空格都可能使 docker compose 直接报错。

1. 启动服务：

docker compose up -d

服务启动后，访问 http://<服务器IP>:3000，进入 GItea 初始化页面。如果你是 linux 部署的服务，windows 和 linux 网络互通，Windows 上的浏览器可以直接访问。

1.2 在网页里完成初始化

1. 打开安装页面，按默认配置完成初始化。
2. 注册管理员账号并登录。

1.3 配置 SSH 密钥

SSH 密钥就像一把钥匙：你用 Git 推送时，Gitea 会验证你的密钥是否匹配，匹配成功才允许操作。这里的场景是从 Linux 推送内容到 Gitea，所以需要把 Linux 上的公钥 添加到 Gitea，让服务器认识这台机器。此时 linux 是客户端，Gitea 是服务段。

1.3.1 生成专用密钥

在 Linux 终端执行以下命令，生成一把专用密钥：

ssh-keygen -t ed25519 -C "gitea-key" -f ~/.ssh/gitea_ed25519

命令执行后会提示设置密码，连续回车跳过即可。完成后会生成两个文件：

• ~/.ssh/gitea_ed25519
  ：私钥，保留在本地，不要分享
• ~/.ssh/gitea_ed25519.pub
  ：公钥，用于添加到 Gitea

1.3.2 将公钥添加到 Gitea

1. 查看并复制公钥内容：

cat ~/.ssh/gitea_ed25519.pub

1. 登录 Gitea，点击右上角头像 -> 设置 -> SSH/GPG 密钥 -> 添加密钥，填写一个名称（如 linux-home），将公钥内容粘贴进去，保存。

验证链接是否正常。

ssh -T -p 222 git@服务器IP

看到 Hi <用户名>! You've successfully authenticated 说明配置成功。

1.3.3 避免密钥冲突

如果你的 Linux 上已经为 GitHub 等其他服务配过 SSH 密钥，建议在 ~/.ssh/config 中为 Gitea 单独配置别名，避免多密钥互相干扰：

Host github.com  HostName github.com  User git  IdentityFile ~/.ssh/id_rsaHost gitea-local 192.168.192.21  HostName 192.168.192.21  Port 222  User git  IdentityFile ~/.ssh/gitea_ed25519

• Host gitea-local
  自定义别名，之后可以直接用这个别名连接，如 git clone gitea-local:user/repo.git
• IdentitiesOnly yes
  强制只使用指定密钥，避免 SSH 把其他密钥也拿去尝试，导致认证混乱

1.4 Gitea 初始化仓库

在 Gitea 中创建测试仓库。点击右上角的➕图标，创建仓库, 填入以下信息。这里我只填了仓库名称：demo，描述：测试流程。说明：默认主分支是 main 分支，如果需要可以自定义修改。

1.5 从 Linux 推送代码

有两种情况：

1. 如果本地是全新项目（从零开始）

cd /path/to/your/projecttouch README.mdgit initgit checkout -b maingit add README.mdgit commit -m "first commit"git remote add origin git@192.168.192.21:wanglei-dev/demo.git # 替换成自己的IP/用户名/仓库名git push -u origin main

上面的命令行依次执行后，Gitea 上的显示效果如下图所示。

1. 本地已有 Git 仓库（只需绑定远程）

cd /path/to/your/projectgit remote add origin git@192.168.192.21:wanglei-dev/demo.git # 替换成自己的IP/用户名/仓库名git push -u origin main

如果你配置了 ~/.ssh/config 中的 gitea-local 别名，地址可以改写为：

git@gitea-local:wanglei-dev/demo.git

刷新 Gitea 仓库页面，确认文件已出现，提交记录正确，整条链路跑通。

通过以上命令行可以看到，github 和 gitea 平时的 git clone、git pull、git push、git add 、git commit 都是同一套用法。

2 最佳实践与应用

如果你想试试这个流程，可以按照以下步骤测试个简单的 DEMO 练练手。

1. 部署 Gitea 并完成初始化。
2. 配置专用 SSH 密钥。
3. 创建测试仓库并推送 README.md。
4. 验证整个流程是否正常。

完成基础配置后，可逐步迁移项目，或设置 GitHub + Gitea 双远程同步。

如果你有更高效的同步备份方案，欢迎在评论区分享你的经验！

3 相关链接

用 Gitea 打通 Windows 与 Linux 的笔记、代码同步