From 8d5c8c6baea4907f78916f4785d19e22025413a87d8dc546b448a62d737e30fb Mon Sep 17 00:00:00 2001 From: Maoayo233 Date: Wed, 23 Sep 2026 02:08:49 +0800 Subject: [PATCH] =?UTF-8?q?docs(deploy):=20=E6=8A=8A=E3=80=8CSSH=20?= =?UTF-8?q?=E9=BB=98=E8=AE=A4=E5=85=B3=E9=97=AD=E3=80=8D=E7=9A=84=E8=AF=B4?= =?UTF-8?q?=E6=98=8E=E5=AF=B9=E9=BD=90=E5=AE=9E=E6=B5=8B,=20=E5=B9=B6?= =?UTF-8?q?=E8=A1=A5=E4=B8=8A=E5=90=AF=E7=94=A8=E6=AD=A5=E9=AA=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 起因是加公钥时页面提示"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)、验证命令和利弊。 --- deploy/README.md | 40 +++++++++++++++++++++++++++++++++++++++- deploy/compose.yaml | 7 +++++-- 2 files changed, 44 insertions(+), 3 deletions(-) diff --git a/deploy/README.md b/deploy/README.md index 6e373dd..9d63978 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -885,7 +885,7 @@ systemctl start gitea`(§9)。 | 配置 | 迁移前 | 现在 | 原因 | |---|---|---|---| | `log.MODE` | `file` | `console` | 日志进 stdout, 用 `docker compose logs` 收集 | -| `server.DISABLE_SSH` | `false` | `true` | 实测 `/home/git/.ssh` 不存在, SSH 从未使用; 避免暴露无法工作的克隆地址 | +| `server.DISABLE_SSH` | `false` | `true` | 只提供 HTTP 克隆地址; 见下面的「如需启用 SSH 克隆」 | | `server.DOMAIN` | `localhost` | 实际主机/IP | `localhost` 会生成错误的克隆地址; `ROOT_URL` 已显式指定, 此项属修正 | | `security.ALLOWED_HOST_LIST` | `[security]`(**正确**) | **保持 `[security]`** | 1.27 的规范位置就是 `[security]`; `[webhook]` 是 v28.0.0 将移除的 deprecated fallback | | `server.HTTP_ADDR` | `0.0.0.0:2080` | 容器内 `0.0.0.0`, 宿主只发布 `127.0.0.1:2080` | 保持 Apache 反代路径不变, 同时消除直连暴露面 | @@ -894,6 +894,44 @@ systemctl start gitea`(§9)。 其余配置(注册策略、OIDC 自动注册、admin 限制、pull-request/signing 默认值、 `PASSWORD_HASH_ALGO=pbkdf2`、`OFFLINE_MODE`、webhook TLS 等)均按原值 1:1 保留。 +#### 如需启用 SSH 克隆(可选, 默认关闭) + +关闭后界面上所有克隆地址都是 HTTP, 加公钥时也会提示"SSH 目前已禁用, 这些密钥仅用于提交 +签名验证"。实测现状(2026-09-23): + +| 事实 | 值 | +|---|---| +| 镜像自带 sshd | **有**: s6 服务 `/etc/s6/openssh`, 容器内**已在 `0.0.0.0:22` 上监听**(只是没发布端口) | +| 发布到宿主 | 没有 —— `docker port gitea` 只有 `3000/tcp -> 127.0.0.1:2080`, 所以外部连不上 | +| git 用户家目录 | `/data/git`(不是旧版镜像的 `/home/git`) | +| 授权文件 | `/data/git/.ssh/authorized_keys`, **由 Gitea 维护**(形如 `command="… gitea serv key-N"`), 所以加过公钥的账号启用后立刻可用, 不用重加 | +| host key | `/data/ssh/ssh_host_{ed25519,rsa,ecdsa}_key`, 在 `/data` 持久卷里(迁移会一起走) | +| 认证策略 | `PasswordAuthentication no` / `AllowUsers git` / `PermitRootLogin no` / `AllowTcpForwarding,AllowAgentForwarding no` —— 只能公钥 | +| 宿主 22 | 被宿主自己的 OpenSSH 占着(`0.0.0.0:22`), 所以 Gitea 得换端口 | + +要启用得同时改三处, 少一处就会出现 `ssh://git@localhost:22/...` 这种没用的克隆地址 +(这正是当初关掉它的原因): + +```yaml +GITEA__server__DISABLE_SSH: "false" +GITEA__server__SSH_DOMAIN: ${GITEA_DOMAIN} # 对外主机; 默认值是 localhost +GITEA__server__SSH_PORT: "2222" # 展示在克隆地址里的端口 +ports: + - "0.0.0.0:2222:22" # 宿主 2222 -> 容器 sshd 的 22 +``` + +然后 `docker compose up -d gitea`(端口变了要重建容器), 验证: + +```bash +ssh -T -p 2222 git@10.80.42.185 # 期望: Hi <用户名>! You've successfully authenticated, ... +``` + +**代价**: 绕过 Apache 多开一个对外的口子(当前 firewalld 未运行 = 校内可达)、多一个攻击面、 +`SSH_DOMAIN`/`SSH_PORT` 必须和实际一致、非 22 端口对使用者不友好。**好处**: 免密推送(私钥 +不出本机), 而当前平台是纯 HTTP —— HTTP 推送的账号密码/token 是 base64 明文过网。 +只需要给自己和几个助教免密的话, 用 HTTP + Personal Access Token + +`git config --global credential.helper 'cache --timeout=604800'` 更省事, 不必动服务器。 + **迁移中发现并处理的既有问题**: | # | 问题 | 证据 | 处理 | diff --git a/deploy/compose.yaml b/deploy/compose.yaml index dc26689..c713f8d 100644 --- a/deploy/compose.yaml +++ b/deploy/compose.yaml @@ -108,8 +108,11 @@ services: GITEA__server__HTTP_ADDR: 0.0.0.0 GITEA__server__HTTP_PORT: "3000" GITEA__server__APP_DATA_PATH: /data/gitea - # 现有部署未启用 SSH(git 用户无 .ssh/authorized_keys), 故关闭。 - # 如需启用容器内置 SSH, 见 deploy/README.md "启用 SSH 克隆"。 + # 关闭 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}