Files
tjhlp-gitea/deploy/compose.yaml
T
admin 8d5c8c6bae docs(deploy): 把「SSH 默认关闭」的说明对齐实测, 并补上启用步骤
起因是加公钥时页面提示"SSH 目前已禁用, 这些密钥仅用于提交签名验证"。查证后修正两处
过时/失效的说明:

- compose 里那行注释让读者去看 deploy/README.md「启用 SSH 克隆」—— 该小节并不存在
- README 兼容性表里 server.DISABLE_SSH 的理由写的是"实测 /home/git/.ssh 不存在"。
  实测(2026-09-23): 容器里 git 用户家目录是 /data/git, /data/git/.ssh/authorized_keys
  存在且由 Gitea 维护(形如 command="… gitea serv key-N"), 加过公钥的账号启用后即可用

新增「如需启用 SSH 克隆(可选, 默认关闭)」小节, 记下查证到的事实: 镜像自带 sshd(s6 服务
openssh, 容器内已在 0.0.0.0:22 监听, 只是没发布端口)、host key 在持久卷 /data/ssh、
sshd_config 只允许 git 用户公钥认证(PasswordAuthentication no / AllowUsers git /
PermitRootLogin no / 不转发)、宿主 22 被宿主自己的 sshd 占用; 以及要同时改的三处
(DISABLE_SSH / SSH_DOMAIN / SSH_PORT + 发布 2222:22)、验证命令和利弊。
2026-09-23 02:08:49 +08:00

244 lines
14 KiB
YAML

# =============================================================================
# TJHLP Gitea + PostgreSQL 部署(docker compose v2)
#
# 目标环境: Rocky Linux 8.10 / aarch64
#
# 设计要点:
# * 版本全部锁定(GITEA_VERSION / POSTGRES_VERSION), 可复现、可回滚
# * Gitea 只发布到 127.0.0.1, 由宿主机 Apache 继续反代 /QA -> 127.0.0.1:2080
# (不放 0.0.0.0, 避免绕过反代与 TLS 直连 2080)
# * PostgreSQL 只在内部网络暴露, 不发布到宿主机
# * 所有 app.ini 配置通过 GITEA__section__KEY 环境变量注入(官方镜像支持),
# 不把宿主绝对路径写进配置文件
# * 数据用 bind mount, 便于备份/检查/回滚(见 deploy/README.md)
#
# 用法:
# cp .env.example .env # 填写密钥与路径
# docker compose up -d --build
# docker compose ps
# =============================================================================
name: gitea
services:
db:
# 官方镜像只生成 en_US.UTF-8, 而现有集群是 zh_CN.UTF-8,
# 因此需要一个只加 locale 的派生镜像, 保证迁移后排序语义一致。
build:
context: ./db
args:
POSTGRES_VERSION: ${POSTGRES_VERSION:-18.6}
image: local/gitea-postgres:${POSTGRES_VERSION:-18.6}-zh_CN
container_name: gitea-db
restart: unless-stopped
environment:
POSTGRES_DB: ${POSTGRES_DB:?POSTGRES_DB is required}
POSTGRES_USER: ${POSTGRES_USER:?POSTGRES_USER is required}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
# 与现有集群保持一致: UTF8 + zh_CN.UTF-8 (见 deploy/README.md 的核对结果)
POSTGRES_INITDB_ARGS: "--encoding=UTF8 --locale=zh_CN.UTF-8"
TZ: ${TZ:-Asia/Shanghai}
volumes:
# ★ postgres:18 起数据目录布局变了(见官方 Dockerfile):
# ENV PGDATA /var/lib/postgresql/18/docker
# VOLUME /var/lib/postgresql ← 不再是 .../data
# 所以必须挂到父目录 /var/lib/postgresql。若仍挂 /var/lib/postgresql/data,
# 入口脚本会通过 mountpoint / /proc/self/mountinfo 检测到"未使用的挂载点"
# 并直接 exit 1(docker_error_old_databases)。
# 宿主机上实际数据落在 ${POSTGRES_DATA_DIR}/18/docker
- ${POSTGRES_DATA_DIR:?POSTGRES_DATA_DIR is required}:/var/lib/postgresql
healthcheck:
test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U \"$$POSTGRES_USER\" -d \"$$POSTGRES_DB\""]
interval: 10s
timeout: 5s
retries: 12
start_period: 60s
networks:
- gitea-internal
gitea:
image: docker.gitea.com/gitea:${GITEA_VERSION:?GITEA_VERSION is required}
container_name: gitea
restart: unless-stopped
depends_on:
db:
condition: service_healthy
environment:
# 与宿主机 git 用户 (uid/gid 982) 对齐, 保证 bind mount 权限正确
USER_UID: ${GITEA_UID:-982}
USER_GID: ${GITEA_GID:-982}
TZ: ${TZ:-Asia/Shanghai}
# --- 站点名 ---------------------------------------------------------
# ★ 必须用【裸变量 APP_NAME】, 不能用 GITEA__DEFAULT__APP_NAME:
# 镜像的 /etc/s6/gitea/setup 用 envsubst 渲染 /etc/templates/app.ini,
# 模板第一行就是 `APP_NAME = $APP_NAME` —— 裸变量才是它的来源。
# 而 GITEA__DEFAULT__APP_NAME 到不了顶层 APP_NAME:
# modules/setting/config_env.go 会把段名小写化(strings.ToLower),
# 而 ini 库(gopkg.in/ini.v1)默认段名常量是 "DEFAULT"(大写, 默认区分大小写),
# 于是只会多出一个没用的 [default] 段。
# 注意: 模板只在 app.ini 不存在时渲染; 已有 app.ini 时改这个变量
# 需要删掉 app.ini 让容器重新生成(见 README 5.3)。
APP_NAME: ${GITEA_APP_NAME:?GITEA_APP_NAME is required}
# --- 去 Gitea 化: 站点元信息与页脚 ----------------------------------
# 不填这些时, meta description 会保留 Gitea 自带的
# "a painless self-hosted Git service", 页脚会显示 Powered by Gitea。
# ★ 段名里的点必须编码成 _0X2E_ (config_env.go 的 GITEA__<段>__<键> 规则),
# 即 app.ini 的 [ui.meta] 段要写成 GITEA__ui_0X2E_meta__XXX。
GITEA__ui_0X2E_meta__AUTHOR: ${GITEA_META_AUTHOR:-同济大学高级语言程序设计课程}
GITEA__ui_0X2E_meta__DESCRIPTION: ${GITEA_META_DESCRIPTION:-同济大学高级语言程序设计课程答疑平台}
GITEA__ui_0X2E_meta__KEYWORDS: ${GITEA_META_KEYWORDS:-同济大学,高级语言程序设计,答疑,Issue}
GITEA__other__SHOW_FOOTER_POWERED_BY: "false"
GITEA__other__SHOW_FOOTER_VERSION: "false"
# --- 数据库 ---------------------------------------------------------
GITEA__database__DB_TYPE: postgres
GITEA__database__HOST: db:5432
GITEA__database__NAME: ${POSTGRES_DB:?POSTGRES_DB is required}
GITEA__database__USER: ${POSTGRES_USER:?POSTGRES_USER is required}
GITEA__database__PASSWD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
GITEA__database__SSL_MODE: disable
GITEA__database__LOG_SQL: "false"
# --- 服务地址(保留 /QA 子路径, 与现有 Apache 反代一致) ---------------
GITEA__server__PROTOCOL: http
GITEA__server__DOMAIN: ${GITEA_DOMAIN:?GITEA_DOMAIN is required}
GITEA__server__ROOT_URL: ${GITEA_ROOT_URL:?GITEA_ROOT_URL is required}
GITEA__server__HTTP_ADDR: 0.0.0.0
GITEA__server__HTTP_PORT: "3000"
GITEA__server__APP_DATA_PATH: /data/gitea
# 关闭 SSH: 界面只提供 HTTP 克隆地址(加公钥时会提示"仅用于提交签名验证")。
# 注意镜像自带 sshd(s6 服务 openssh), 容器内就在 22 上监听 —— 只是没有发布端口。
# 启用要同时改 DISABLE_SSH / SSH_DOMAIN / SSH_PORT 并在 ports 里发布 2222:22,
# 少改一处就会出现 ssh://git@localhost:22/... 这种坏地址: 见
# deploy/README.md「如需启用 SSH 克隆(可选, 默认关闭)」。
GITEA__server__DISABLE_SSH: "true"
GITEA__server__LFS_START_SERVER: "true"
GITEA__server__OFFLINE_MODE: ${GITEA_OFFLINE_MODE:-true}
# --- 路径(全部在 /data 内, 不依赖宿主路径) ---------------------------
GITEA__repository__ROOT: /data/git/repositories
GITEA__lfs__PATH: /data/git/lfs
GITEA__indexer__ISSUE_INDEXER_PATH: /data/gitea/indexers/issues.bleve
GITEA__session__PROVIDER: file
GITEA__session__PROVIDER_CONFIG: /data/gitea/sessions
# 容器里日志直接进 stdout, 用 docker compose logs / journald 查看
GITEA__log__MODE: console
GITEA__log__LEVEL: info
# --- 密钥(必须沿用现有值, 否则加密数据/令牌失效) --------------------
GITEA__security__INSTALL_LOCK: "true"
# 现有 /etc/gitea/app.ini 未设置 SECRET_KEY, 实例实际使用 Gitea 内置默认值。
# 留空即保持同一行为(SSO/加密数据不受影响); 旋转换 key 见 deploy/README.md。
GITEA__security__SECRET_KEY: ${GITEA_SECRET_KEY:-}
GITEA__security__INTERNAL_TOKEN: ${GITEA_INTERNAL_TOKEN:?preserve the existing INTERNAL_TOKEN}
GITEA__security__PASSWORD_HASH_ALGO: pbkdf2
GITEA__server__LFS_JWT_SECRET: ${GITEA_LFS_JWT_SECRET:?preserve the existing LFS_JWT_SECRET}
GITEA__oauth2__JWT_SECRET: ${GITEA_OAUTH2_JWT_SECRET:?preserve the existing JWT_SECRET}
# --- 注册与登录(与现有 app.ini 一致: 仅允许外部 OIDC 注册) ----------
GITEA__service__DISABLE_REGISTRATION: "false"
GITEA__service__ALLOW_ONLY_EXTERNAL_REGISTRATION: "true"
GITEA__service__REGISTER_EMAIL_CONFIRM: "false"
GITEA__service__ENABLE_NOTIFY_MAIL: "false"
GITEA__service__ENABLE_CAPTCHA: "false"
GITEA__service__REQUIRE_SIGNIN_VIEW: "false"
# 不做通行密钥(WebAuthn): 上游登录页的 passkey 区块只有 tw-hidden 的元素,
# 浏览器不支持条件中介时就渲染成一个空方框; 关闭后区块不再输出。
GITEA__service__ENABLE_PASSKEY_AUTHENTICATION: "false"
GITEA__service__DEFAULT_KEEP_EMAIL_PRIVATE: "false"
GITEA__service__DEFAULT_ALLOW_CREATE_ORGANIZATION: "true"
GITEA__service__DEFAULT_ENABLE_TIMETRACKING: "true"
GITEA__service__NO_REPLY_ADDRESS: ${GITEA_NO_REPLY_ADDRESS:?GITEA_NO_REPLY_ADDRESS is required}
GITEA__mailer__ENABLED: "false"
# --- OIDC / OAuth2 --------------------------------------------------
GITEA__openid__ENABLE_OPENID_SIGNIN: "false"
GITEA__openid__ENABLE_OPENID_SIGNUP: "true"
GITEA__oauth2_client__OPENID_CONNECT_SCOPES: profile email
GITEA__oauth2_client__ENABLE_AUTO_REGISTRATION: "true"
GITEA__oauth2_client__USERNAME: userid
GITEA__oauth2_client__ACCOUNT_LINKING: auto
# [oauth2] ENABLED 默认即为 true, 现有 app.ini 未显式设置;
# 这里显式声明, 避免上游改默认值时行为漂移
GITEA__oauth2__ENABLED: "true"
# --- 出站代理: 显式给值挡掉 compose 的自动注入, 默认【不用代理】 --------
# ★ docker compose 会把【运行 compose 的那个 shell 里】的 http_proxy/https_proxy
# 自动注入容器。本机登录 shell 里是 127.0.0.1:7890, 而那个地址在容器里指向
# 容器自己, 于是 Gitea 启动时 OIDC discovery 失败:
# initOAuth2Sources() [E] Unable to register source: 高程统一身份认证 due to
# proxyconnect tcp: dial tcp 127.0.0.1:7890: connect: connection refused
# 后果: /user/oauth2/<认证源> 返回 404, 统一身份认证登录不可用(2026-09-11 实际踩到)。
# 显式赋值可以挡住注入 —— 哪怕给的是空值。
#
# 不用代理的理由(2026-09-13 实测):
# * 容器直连外网是通的 —— dl.gitea.com / api.github.com / codeload.github.com
# 在容器里直接 curl 都是 200/301(github.com 主站直连会超时, 但平台不依赖它);
# * 功能相关的出站只有 OIDC, 目标是 10.80.42.185, 容器内直连就是 200;
# * 宿主 7890 那个代理是 ssh 转发的开发用代理, 只监听宿主 127.0.0.1,
# 容器里连不上(127.0.0.1:7890 是容器自己; 10.80.42.185:7890 实测 connect refused)。
# 将来真要给容器配代理, 必须是【容器可达】的地址(隧道绑 LAN 口, 或用 host 网络兜底),
# 再在 deploy/.env 里给 GITEA_HTTP_PROXY。
HTTP_PROXY: ${GITEA_HTTP_PROXY:-}
HTTPS_PROXY: ${GITEA_HTTPS_PROXY:-}
http_proxy: ${GITEA_HTTP_PROXY:-}
https_proxy: ${GITEA_HTTPS_PROXY:-}
NO_PROXY: ${GITEA_NO_PROXY:-localhost,127.0.0.1,::1,10.80.42.185,.local,.internal}
no_proxy: ${GITEA_NO_PROXY:-localhost,127.0.0.1,::1,10.80.42.185,.local,.internal}
# --- 管理员限制 -----------------------------------------------------
GITEA__admin__DISABLE_REGULAR_ORG_CREATION: "true"
GITEA__admin__EXTERNAL_USER_DISABLE_FEATURES: deletion,manage_credentials,change_username,change_full_name
# --- 其它(沿用现有 app.ini) ----------------------------------------
GITEA__cron.update_checker__ENABLED: "true"
GITEA__repository.pull-request__DEFAULT_MERGE_STYLE: merge
GITEA__repository.signing__DEFAULT_TRUST_MODEL: committer
# --- Webhook 出站白名单 ---------------------------------------------
# ★ 该键在 1.27 的规范位置是 [security], 不是 [webhook]。
# 证据: modules/setting/webhook.go (v1.27.3)
# deprecatedSetting(rootCfg, "webhook", "ALLOWED_HOST_LIST",
# "security", "ALLOWED_HOST_LIST", "v28.0.0")
# Webhook.AllowedHostList = sec.Key("ALLOWED_HOST_LIST").MustString(Security.AllowedHostList)
# 即 [webhook] 是 v28.0.0 将移除的 fallback。而且读取时 [webhook] 的值
# 【优先于】[security], 所以千万不要两处都写。
GITEA__security__ALLOWED_HOST_LIST: ${GITEA_ALLOWED_HOST_LIST:?GITEA_ALLOWED_HOST_LIST is required}
# SKIP_TLS_VERIFY 确实属于 [webhook](webhook.go 里就是读 [webhook] 段)
GITEA__webhook__SKIP_TLS_VERIFY: "true"
volumes:
- ${GITEA_DATA_DIR:?GITEA_DATA_DIR is required}:/data
# --- 定制覆盖层(Gitea 客制化, 见 customization/README.md) ------------
# ★ 官方镜像里 GITEA_CUSTOM=/data/gitea, 所以定制文件对应
# /data/gitea/{templates,public,options},
# 不是 /data/gitea/custom(那是源码/二进制安装 WorkPath/custom 的写法,
# 在容器里挂了不会生效)。
# 分开挂三个子目录而不是整目录: 只读覆盖定制内容, 又不遮住同级的
# conf/、log/、indexers/ 等容器自己管理的目录。
# entrypoint 只在 /data/gitea 属主不是 git 时才 chown -R, 现有
# ${GITEA_DATA_DIR}/gitea 属主已是 git, 不会去碰只读挂载。
- ${GITEA_CUSTOM_DIR:?GITEA_CUSTOM_DIR is required}/templates:/data/gitea/templates:ro
- ${GITEA_CUSTOM_DIR:?GITEA_CUSTOM_DIR is required}/public:/data/gitea/public:ro
- ${GITEA_CUSTOM_DIR:?GITEA_CUSTOM_DIR is required}/options:/data/gitea/options:ro
- /etc/localtime:/etc/localtime:ro
ports:
# 只绑定回环: Apache 反代 /QA -> 127.0.0.1:2080, 不对外暴露
- "127.0.0.1:${GITEA_HTTP_PORT:-2080}:3000"
# 上游 Dockerfile 里有 "HEALTH-CHECK-ENDPOINT: don't use HEALTHCHECK" 的提示,
# 这里显式提供一个: 镜像内自带 curl, /api/healthz 是官方健康端点。
healthcheck:
test: ["CMD", "curl", "-fsS", "http://127.0.0.1:3000/api/healthz"]
interval: 15s
timeout: 5s
retries: 10
start_period: 90s
networks:
- gitea-internal
networks:
gitea-internal:
driver: bridge