Gitea 群晖 Container Manager 部署文档

适用环境：群晖 DSM，Container Manager（Docker）部署，局域网内网Git代码仓库。 Gitea是自托管Git代码托管服务，用于保存代码版本历史，台式机本地多硬盘代码项目，通过Git命令推送备份至NAS。

1. 前置准备

  1. 在File Station创建项目目录
    • 新建目录：/volumeX/docker/gitea
    • 自动生成子目录：data（存放仓库代码、配置、数据库）

      将volumeX替换为NAS实际存储卷编号

  2. 目录权限说明 Gitea容器默认使用UID=1000、GID=1000运行。新建文件夹后，在文件夹属性中，给docker用户组读写权限，避免权限报错。
  3. 端口规划
    • 网页访问端口：3000
    • Git SSH端口：2222（不与群晖本身22端口冲突）

2. docker-compose.yml

新建docker-compose.yml文件，完整内容：

services:
  gitea:
    image: gitea/gitea:latest
    container_name: gitea
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai
      - USER_UID=1000
      - USER_GID=1000
    volumes:
      - ./data:/data
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "2222:22"
    networks:
      - gitea_net

networks:
  gitea_net:

说明：内置SQLite数据库，无需额外Postgres容器，轻量部署，适合个人代码仓库使用。如需大容量多用户场景，可替换为外置Postgres。

3. Container Manager部署操作步骤

  1. 打开群晖「Container Manager」→「项目」→「创建」
  2. 项目名称填写：gitea
  3. 来源选择：上传compose文件，选中上面保存好的docker-compose.yml
  4. 下一步，确认配置，勾选「自动启动」
  5. 完成创建，等待镜像拉取并启动容器。

4. 网页初始化配置

  1. 浏览器局域网访问地址：http://NAS内网IP:3000
  2. 首次打开自动进入安装页面，核心配置项：
    • 数据库类型：SQLite3（默认，无需修改）
    • 站点名称：自定义，例如NAS代码仓库
    • 站点URL：http://NAS内网IP:3000
    • 管理员账号：填写自定义用户名、管理员密码（记录好）
  3. 拉到页面最底部，点击「立即安装Gitea」
  4. 安装完成自动跳转登录页面，使用管理员账号密码登录。

5. 台式机本地代码推送（多硬盘项目管理）

原理：台式机本地硬盘为工作区，Gitea（NAS）存放远端版本仓库；一个代码项目对应Gitea一个仓库，多硬盘项目互相独立。

5.1 在Gitea网页新建仓库

  1. 登录Gitea → 右上角加号 → 新建仓库
  2. 填写仓库名称，勾选「初始化仓库」，创建。
  3. 创建完成页面会展示仓库地址，示例： http://NAS内网IP:3000/你的用户名/项目名.git

5.2 台式电脑Git操作（Windows）

前提：台式机安装Git工具，打开Git Bash，进入本地代码文件夹（D盘/E盘/不同硬盘均可）

# 项目首次初始化（仅第一次执行）
git init
git add .
git commit -m "项目初始提交"
# 关联NAS上Gitea远端仓库，替换为你的仓库地址
git remote add origin http://NAS内网IP:3000/你的用户名/项目名.git
# 推送代码到NAS Gitea
git push -u origin main

5.3 日常代码修改后备份推送

git add .
git commit -m "本次修改备注"
git push

git push：把本地修改快照上传备份到NAS的Gitea远端仓库，保存完整版本历史。 git pull：从NAS拉取远端最新代码到本地电脑。

6. 备份与维护

6.1 数据备份

Gitea全部仓库代码、账号配置、数据库保存在挂载目录 /volumeX/docker/gitea/data。 定期备份整个data目录，NAS硬盘损坏时，复制该目录+相同compose配置，即可完整恢复所有代码仓库。

6.2 版本升级

Container Manager项目页面，重新拉取最新镜像，重启项目，自动完成Gitea升级，数据不会丢失。

7. 常见问题排查

  1. 网页打不开，容器反复重启
    • 检查/volumeX/docker/gitea/data文件夹权限，确保UID=1000用户读写权限。
    • 查看容器日志，确认目录权限报错。
  2. 台式机git push推送失败
    • 确认台式机可以访问NAS内网3000端口；
    • 核对Gitea仓库地址、账号密码。
  3. SSH克隆仓库 使用SSH地址克隆时，端口使用2222，示例：git@NAS内网IP:2222:用户名/仓库.git
  4. 忘记管理员密码 进入Gitea容器终端，执行命令重置管理员密码
     gitea admin user change-password --username 管理员用户名 --password 新密码

8. 使用说明（重点）

  1. Gitea不会自动扫描台式机硬盘文件，修改代码后必须手动执行git push，才会备份版本到NAS。
  2. 项目隔离：台式机不同硬盘、不同文件夹内的代码，在Gitea分别创建独立仓库，不要多个项目放入同一个仓库，避免版本混乱。
  3. 不建议将虚拟机镜像、压缩包等大二进制文件存入Git仓库，Git适合管理源码文本文件。