命令	功能
`just gitea init`	创建缺失的密钥、配置和数据目录，保留已有内容，并验证 Compose；不启动服务。
`just gitea deploy`	自动初始化并部署 Gitea，启用 GitHub 明暗主题，发布宿主机 3000 端口。
`just gitea deploy proxy`	自动初始化并部署 Gitea，启用 GitHub 明暗主题，接入已有的 `web-network`，取消宿主机端口映射。

首次部署：

just gitea init
# 编辑 gitea/conf/app.ini，设置域名和 ROOT_URL
just gitea deploy

使用反向代理时，执行 just gitea deploy proxy，代理通过同一网络中的 server:3000 访问。每次部署都需要指定所需模式。

配置文件为 conf/app.ini，密钥保存在 .env，服务数据保存在 data/。初始化从 conf/app.ini.example 复制配置；默认配置锁定安装流程，不创建管理员账号。迁移实例需要恢复原有配置、密钥和数据。

主题预览

命令	功能
`just gitea theme preview on`	启动预览，地址为 http://localhost:3001 。
`just gitea theme preview off`	停止并移除预览容器，保留数据卷。
`just gitea theme preview restart`	重启预览服务，重新加载模板。
`just gitea theme preview logs`	持续查看预览日志。

预览使用独立数据卷，只开放本机 3001 端口。首次使用需要创建预览账号和示例仓库。

主题使用原生 CSS，直接挂载，无需编译。修改 CSS 后刷新浏览器；修改模板后执行 just gitea theme preview restart。顶部太阳／月亮按钮切换明暗配色。

位置	用途
`themes/compose-preview.yaml`	预览环境配置。
`themes/css/theme-github-dev*.css`	明暗主题入口。
`themes/css/colors-light.css`、`colors-dark.css`	明暗配色变量。
`themes/css/fonts.css`、`shared.css`	字体引用与共用样式加载顺序。
`themes/css/controls/`	按钮、输入框、菜单等通用控件。
`themes/css/components/`	仓库、Issue、Actions 等业务区域。
`themes/css/pages.css`	页面布局。
`themes/templates/`	Gitea 模板覆盖。

Runner

Runner 通过 runner/compose.yaml 独立部署，配置项见 runner/.env.example。需要已有的 web-network、外部数据卷 gitea_act-runner-data 和 Docker socket。Gitea 主服务部署命令不会启动 Runner。