Gitea 的价值是让脚本、Compose 和记录有版本历史。

\n
Gitea 放在 HomeLab 里，不只是为了有一个私有 Git 页面。它真正有价值的地方，是把 compose 文件、脚本、维护记录、配置模板和小工具代码纳入版本历史。家用服务器经常是一边使用一边调整，如果没有仓库，很多改动只能靠记忆追溯。Gitea 可以让这些变化变成可查看、可回滚、可讨论的记录。

仓库目录要规划清楚

Gitea 容器通常会挂载一个 data 目录，里面包含仓库、附件、头像、索引和应用配置。这个目录不能和其他服务混在一起，也不要放到临时下载区。我的习惯是给它单独项目目录，例如 gitea/compose.yml、gitea/data/、gitea/backup/，再把数据库备份放到明确位置。目录名朴素一点，迁移时更少出错。

仓库内容也要分层。HomeLab 配置仓库里可以放 compose、脚本、说明文档和脱敏示例，但不要放真实密钥、数据库导出、证书私钥和大体积附件。第一天就写 .gitignore，比事后清理历史可靠。已经误提交过敏感内容时，只从当前文件删除还不够，还要处理历史记录和相关凭据。

SSH 和 HTTP 各有边界

Gitea 常见访问方式有 HTTP 页面和 Git over SSH。HTTP 适合浏览、创建 issue、管理用户；SSH 适合日常 push 和 pull。家用环境里最常见的问题是 SSH 端口和宿主机本身的 22 端口冲突。可以把容器 SSH 映射到一个单独端口，例如宿主机 2222，再在页面里配置正确的 SSH 域名和端口，避免克隆地址生成错误。

如果只在内网使用，HTTP 入口不一定要暴露到更大范围。需要远程访问时，前面应有统一认证、HTTPS 和访问限制。Gitea 里存的通常是基础设施说明，一旦被误访问，别人能看到服务结构、目录习惯和部署方式。它不是普通展示页面，应按管理系统保护。

备份不能只复制 data

Gitea 的备份要考虑一致性。仓库文件在 data 目录里，用户、权限、issue、pull request、组织、release 等信息通常还依赖数据库。使用 SQLite 时，数据库文件可能也在 data 里；使用外部数据库时，还要单独备份数据库。只复制仓库目录，恢复后可能还能看到 Git 历史，但页面状态、账号权限和附件会缺失。

我会定期做两种备份：一份是停服务或低活动窗口下的目录快照，一份是应用或数据库层面的导出。恢复演练要在临时目录或测试容器里做，确认能登录、能 clone、能 push、能看到附件和 issue。没有恢复演练的仓库备份，只能算“看起来有文件”。

Runner 不要无限授权

Gitea Actions 或外部 runner 很方便，可以自动检查脚本、构建小工具、发布静态页面。但 runner 的边界要格外小心。它会执行仓库里的任务定义，如果把 Docker socket、宿主机目录或高权限密钥给得太随意，一个错误工作流就可能影响整台服务器。家用环境里，我更倾向先让 runner 只做低风险任务，比如 lint、文档生成、配置语法检查。

需要构建镜像或部署服务时，最好为 runner 单独准备账号、目录和权限，不要直接让它接管全部 Docker 环境。手动部署和自动化部署之间要有清楚分界：哪些仓库能触发，触发后能访问哪些目录，失败时是否会回滚，日志保存在哪里。这些比“能跑通一次”更重要。

日常维护方式

Gitea 升级前，我会先记录当前镜像版本、数据库类型、data 目录大小和最近一次备份时间。升级后检查四件事：Web 登录、SSH clone、仓库 push、附件访问。遇到页面能开但 SSH 失败，先看端口映射和 Gitea 生成的克隆地址；遇到 push 权限问题，先看用户 key、仓库权限和容器日志。

一台 HomeLab 可以没有很复杂的研发流程，但最好有版本历史。Gitea 的目标不是把家庭服务器变成公司平台，而是让每一次配置变化都有迹可循。只要仓库目录、入口协议、备份和 runner 权限这几块稳住，它会成为后续维护里非常可靠的地基。

我还会给仓库设置最小协作规则：主配置仓库不直接在服务器上随手改，改动先提交，再部署；临时脚本可以放实验目录，确认稳定后再合并。这个习惯能减少“服务器上有一份、仓库里另一份”的分叉，也方便以后追踪某次服务异常到底对应哪次配置变化。