记一次 TortoiseGit SSH 认证失败的排查与修复

2026-05-05T16:00:00+08:00

用 TortoiseGit 拉取自托管 Gitea 仓库时，弹出了 TortoiseGitPlink 的安全提示，确认后却提示 "No supported authentication methods available"。折腾了一圈才把问题全部解决，记录一下排查思路和解决方案。

环境</a> </h2>
排查路线</a> </h2> 1. 主机密钥缓存</a> </h3> 首次连接 SSH 服务器时，TortoiseGitPlink 会弹出安全提示框，询问是否信任服务器的主机密钥。点击"是"即可缓存，这是正常的 SSH 安全机制。 2. Pageant 进程干扰</a> </h3> 确认主机密钥后仍然失败，报 "Server refused our key"。检查任务管理器发现 Pageant（PuTTY 认证代理）正在后台运行。 TortoiseGitPlink 默认会优先使用 Pageant 中已加载的密钥，而不是远端设置中指定的 .ppk</code> 文件。如果 Pageant 中没有加载正确的密钥，就会认证失败。 在 Pageant 中添加 .ppk</code> 文件后仍然失败，决定放弃 TortoiseGitPlink，改用系统自带的 OpenSSH。 3. 密钥格式转换</a> </h3> TortoiseGit 的 SSH 客户端切换到 OpenSSH 后，需要 OpenSSH PEM 格式的私钥，而不是 .ppk</code>。 PuTTYgen 的 GUI 可以手动做转换，但命令行参数在这个版本中不理想。最后用 Python 的 cryptography</code> 库直接解析 .ppk</code> 文件： import base64 from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey from cryptography.hazmat.primitives import serialization with open("key.ppk") as f: lines = f.readlines() # 提取 Private-Lines 的 base64 数据 private_b64 = "" in_private = False for line in lines: line = line.strip() if line == "Private-Lines: 1": in_private = True continue if in_private and line.startswith("Private-MAC:"): break if in_private: private_b64 += line raw = base64.b64decode(private_b64) length = int.from_bytes(raw[:4], "big") seed = raw[4 : 4 + length] key = Ed25519PrivateKey.from_private_bytes(seed) pem = key.private_bytes( encoding=serialization.Encoding.PEM, format=serialization.PrivateFormat.OpenSSH, encryption_algorithm=serialization.NoEncryption(), ) with open("key_openssh", "wb") as f: f.write(pem)</code></pre>4. 文件权限</a> </h3> OpenSSH 对私钥文件的权限非常严格。从 .ppk</code> 转换出来的 PEM 文件默认权限太宽松，OpenSSH 会直接拒绝加载： Bad permissions. Try removing permissions for user: ...</code></pre> 用 PowerShell 修复： $acl = Get-Acl -LiteralPath "key" $acl.SetAccessRuleProtection($true, $false) $rule = New-Object System.Security.AccessControl.FileSystemAccessRule( $env:USERNAME, "FullControl", "Allow" ) $acl.SetAccessRule($rule) Set-Acl -LiteralPath "key" -AclObject $acl</code></pre>5. SSH 配置</a> </h3> 为了避免每次在 URL 中硬编码端口 2222，把配置写进 ~/.ssh/config</code>： Host gitea.logfun.xyz HostName gitea.logfun.xyz Port 2222 User git IdentityFile "D:/path/to/key" IdentitiesOnly yes</code></pre> 远程 URL 也从 ssh://git@host:2222/...</code> 改为 SCP 格式 git@host:...</code>，端口由配置文件自动处理。 6. Git SSH 变体</a> </h3> 切换 OpenSSH 后拉取，遇到： fatal: ssh variant 'simple' does not support setting port</code></pre> Git 默认的 SSH 变体是 simple</code>，不支持在 URL 中解析端口。解决方案是全局配置： git config --global ssh.variant ssh git config --global core.sshCommand "ssh -F C:/Users/$USER/.ssh/config"</code></pre> 这样就告诉 Git 使用完整的 OpenSSH 功能，包括端口解析和配置文件。 最终配置</a> </h2> 项目</th> 值</th></tr></thead> SSH 客户端</td> C:\Windows\System32\OpenSSH\ssh.exe</code></td></tr> 远程 URL</td> git@gitea.logfun.xyz:user/repo.git</code></td></tr> 私钥</td> OpenSSH PEM 格式（非 .ppk</code>）</td></tr> 端口管理</td> ~/.ssh/config</code></td></tr> </tbody></table> 总结</a> </h2> 这次排查涉及了六个独立的环节，任何一个出问题都会导致认证失败： 主机密钥缓存 — 首次连接必须确认</li> Pageant 冲突 — 运行 Pageant 时 TortoiseGitPlink 的行为会改变</li> 密钥格式 — .ppk</code> 和 OpenSSH PEM 不互通</li> 文件权限 — OpenSSH 对私钥有严格的 ACL 要求</li> SSH 配置 — 用 config 文件管理端口和密钥，而不是 URL</li> Git SSH 变体 — 默认 simple</code> 模式功能受限</li> </ol> 对于 Windows 上的 TortoiseGit 用户，如果使用非标准 SSH 端口（2222、443 等），直接切换到系统 OpenSSH 并通过 ~/.ssh/config</code> 管理配置，比纠结 TortoiseGitPlink + Pageant 要省心得多。 给 Zola 博客添加中文全文搜索 2026-05-05T14:00:00+08:00 Zola 自带的搜索索引基于简单的关键词匹配，对中文的支持不够理想——中文需要分词才能准确搜索。而 Pagefind</a> 是一个专门为静态站点设计的搜索工具，内置对中日韩 (CJK) 文字的支持，索引构建快，前端体积小。 本博客第一篇就提到了 Pagefind，但一直没有真正用上。这次我基于 serene 主题，给它接入了 Pagefind 的中文搜索。 安装 Pagefind</a> </h2> Pagefind 以 npm 包形式发布，但实际调用的是原生二进制。最简单的用法： npm install -g pagefind</code></pre> 安装后在项目里跑： zola build pagefind --site public</code></pre> 它会分析 public/</code> 目录中所有 HTML 文件，生成搜索索引到 public/pagefind/</code>。 如果遇到 SyntaxError: Unexpected token '?'</code> 的错误，说明系统的 Node.js 版本太旧（低于 14）。Pagefind 的 npm 包装在 node_modules/@pagefind/linux-x64/bin/pagefind_extended</code>，可以直接调用这个原生二进制。 集成搜索 UI</a> </h2> Pagefind 自带一个搜索界面组件，包含搜索框、结果列表和高亮功能。只需在页面中加载它的 CSS 和 JS。 Serene 主题提供了 _head_extend.html</code> 扩展点，会注入到每个页面的 <head></code> 中。我利用这个文件做了三件事： 1. 加载 Pagefind 资源和搜索覆盖层</a> </h3> <link href="/pagefind/pagefind-ui.css" rel="stylesheet"> <div id="search-overlay" hidden> <div class="search-modal"> <div id="search"></div> </div> </div> <script src="/pagefind/pagefind-ui.js"></script></code></pre>2. 初始化搜索组件</a> </h3> const ui = new PagefindUI({ element: '#search', showSubResults: true });</code></pre>3. 添加快捷键和按钮</a> </h3> 支持的打开方式：点击页面右下角的搜索按钮、按 Ctrl+K</code>（Mac 上 Cmd+K</code>），或点击首页导航栏的搜索图标。按 Esc</code> 或点击遮罩层关闭。 每次打开搜索时，输入框会自动获得焦点，可以直接打字搜索。 适配暗色模式</a> </h2> Pagefind 的 UI 默认是亮色主题。为了适配 serene 的暗色模式，我通过 CSS 变量来覆盖 Pagefind 的颜色： .pagefind-ui__search-input { background: var(--bg-color); color: var(--text-color); border-color: var(--text-decoration-color); }</code></pre> 这样当用户切换暗色模式时，搜索框的颜色也会随之变化。 中文搜索效果</a> </h2> Pagefind 会自动检测页面语言。本博客的中文内容被正确识别，搜索时可以进行中文分词。实测搜索「Zola」「主题」「博客」等关键词都能精确匹配到对应文章。 Pagefind 的搜索特性： 模糊匹配：大小写不敏感，支持拼写纠错</li> 子标题结果：showSubResults</code> 可以展开到段落级别</li> 多语言：自动按语言分索引，不会混检</li> 轻量：前端 JS 约 30KB（gzip 后）</li> </ul> 完整构建流程</a> </h2> 加入搜索后，构建命令变为两步： zola build # 生成静态页面 pagefind --site public # 构建搜索索引</code></pre> pagefind</code> 命令必须在 zola build</code> 之后执行，因为它读取的是生成好的 HTML 文件。 我把这个流程写到了 AGENTS.md 中，避免下次忘记先后顺序。 总结</a> </h2> 从安装到集成完成大约花了 20 分钟： 步骤</th> 时间</th></tr></thead> 安装 Pagefind</td> 3 分钟</td></tr> 编写搜索覆盖层</td> 8 分钟</td></tr> 适配暗色模式</td> 4 分钟</td></tr> 测试调优</td> 5 分钟</td></tr> </tbody></table> Pagefind 的中文搜索能力超出了我的预期。它不依赖任何后端服务，构建后纯静态运行，非常适合 Zola 这类静态站点生成器。 如果你也想给自己的博客加上搜索，Pagefind 是目前最省心的方案，尤其是需要支持中文的时候。 给 Zola 博客换上 serene 主题 2026-05-05T10:30:00+08:00 本博客的第一篇文章介绍了如何从零搭建 Zola 博客——手写模板、自建样式。但维护一套完整的模板工作量不小。于是我把目光投向了现成主题。 选主题</a> </h2> Zola 官方市场有 120+ 个主题。我的筛选条件： 文档类风格：左侧导航 + 内容区 + 右侧目录</li> 维护活跃：最近一年内有提交</li> Star 数高</li> </ul> 我写了个脚本扫了一遍所有主题的 GitHub 数据，按 star 降序取前 10，过滤掉两年以上没更新的。最终选了 serene</a>： 指标</th> 值</th></tr></thead> Star</td> 355（Zola 主题最高）</td></tr> 最后提交</td> 2026-02-14</td></tr> 类型</td> 个人博客 / 文档</td></tr> </tbody></table> Serene 的设计干净、有暗色模式、自带搜索和目录。虽然它不是严格意义上的文档主题，但它的 prose.html</code> 模板可以很好地承载文档内容。 安装主题</a> </h2> Serene 的 GitHub 仓库提供了两种安装方式。先试了 Git 子模块： git submodule add -b latest https://github.com/isunjn/serene.git themes/serene</code></pre> 但服务器连 GitHub 的速度太慢，clone 超时了。改为手动下载： curl -sL https://github.com/isunjn/serene/archive/refs/heads/latest.tar.gz -o /tmp/serene.tar.gz tar xzf /tmp/serene.tar.gz -C /tmp cp -r /tmp/serene-latest themes/serene</code></pre> 手动下载的好处是不依赖 Git，在任何环境都能装。缺点是后续更新需要手动重复这个过程，而子模块只需 git submodule update --remote</code>。 配置</a> </h2> Serene 自带一个 config.example.toml</code>，复制过来改： cp themes/serene/config.example.toml zola.toml</code></pre> 然后根据本博客的情况修改： base_url</code> → https://blog.logfun.xyz</code></li> title</code> → LLS Blog</code></li> description</code> → 记录技术、编程与生活的点滴</code></li> default_language</code> → zh</code></li> blog_section_path</code> → /blog</code>（我原来就用这个路径，保持一致）</li> </ol> 关键配置项说明： [extra] sections = [ { name = "blog", path = "/blog", is_external = false }, ] blog_section_path = "/blog" force_theme = false # false=跟随系统/手动切换 footer_credits = true # 显示 "Powered by Zola & Serene"</code></pre> force_theme</code> 如果设为 "light"</code> 或 "dark"</code> 会锁定一个模式，设为 false</code> 则用户可自由切换。 设置首页</a> </h2> Serene 的首页不是自动生成的，需要在 content/_index.md</code> 里配置： +++ template = "home.html" [extra] lang = "zh" name = "lss6378" bio = "写代码，写博客，写生活" avatar = "img/avatar.webp" links = [ { name = "GitHub", icon = "github", url = "https://github.com/lss6378" }, ] recent = true recent_max = 10 +++</code></pre> avatar = "img/avatar.webp"</code> 指的是 static/img/avatar.webp</code>。如果没有头像文件，主题会显示一个占位框。头像建议用 webp 格式，体积小加载快。 迁移博客内容</a> </h2> 原来的内容结构是： content/ └── blog/ ├── _index.md ├── zola-blog-setup-guide.md └── zola-theme-custom-domain.md</code></pre> Serene 要求博客内容放在 content/blog/</code> 下，这刚好和我原来的结构一致，不需要移动文件。但需要调整两个地方： 博客分区 _index.md</a> </h3> Serene 的博客模板叫 blog.html</code>，文章页模板叫 post.html</code>： +++ title = "博客" description = "技术、编程与生活" sort_by = "date" template = "blog.html" page_template = "post.html" insert_anchor_links = "right" generate_feeds = true [extra] lang = "zh" title = "博客" subtitle = "记录技术与生活" date_format = "%Y-%m-%d" toc = true back_to_top = true copy = true +++</code></pre>文章 front matter</a> </h3> Serene 的文章 front matter 比 Zola 默认多了一些字段。主要是 [extra]</code> 里的配置项： [extra] lang = "zh" toc = true # 显示目录 comment = false # 关闭评论 copy = true # 代码块显示复制按钮</code></pre> Serene 还支持 featured</code>、math</code>、mermaid</code>、outdate_alert</code> 等。 构建</a> </h2> 删掉旧的模板和样式文件，让 serene 接管： rm -rf templates/ sass/ zola build</code></pre> 第一次构建会编译 serene 的 SCSS，生成 main.css</code>。看到输出行显示 "2 pages, 1 section"，说明一切正常。 打开浏览器访问首页，头像、名称、bio、最近文章列表都正确渲染。暗色模式切换也正常工作。 自定义域名</a> </h2> 主题切换不影响域名配置。Caddyfile 不需要任何改动，继续用原来的配置： blog.logfun.xyz { encode zstd gzip root * /home/ubuntu/blog/lls_blog/public file_server tls lss6378@gmail.com }</code></pre> 唯一要注意的是重新构建后 Caddy 不需要重启——它直接从 public/</code> 目录读文件。 总结</a> </h2> 从自建模板切换到 serene 的整个过程大约 30 分钟： 步骤</th> 时间</th></tr></thead> 下载主题</td> 2 分钟</td></tr> 配置 zola.toml</td> 5 分钟</td></tr> 设置首页</td> 5 分钟</td></tr> 迁移内容</td> 10 分钟</td></tr> 调整调试</td> 8 分钟</td></tr> </tbody></table> Serene 的代码质量很高，CSS 变量体系完善，暗色模式、代码复制、目录导航等都是开箱即用。如果你想给自己的 Zola 博客换个主题，serene 是个很好的起点。 使用 Zola 搭建静态博客 2026-05-05T09:00:00+08:00 为什么选择 Zola</a> </h2> 在 2026 年的今天，静态站点生成器已经多如牛毛。Jekyll、Hugo、Next.js、Astro……每个都有自己的拥趸。但我最终选择了 Zola</a>，原因很简单： 单二进制 — 不需要 Node.js、不需要 Ruby、不需要 Python。下载一个可执行文件就能跑。</li> 速度快 — Zola 用 Rust 编写，构建几百篇文章也就是毫秒级的事。</li> 没有 JavaScript 依赖 — 默认输出纯 HTML + CSS，干净利落。</li> 语法高亮内建 — 不用额外配置。</li> 模板语言 Tera — 如果你熟悉 Jinja2 或 Django 模板，上手零成本。</li> </ul> 安装 Zola</a> </h2> Zola 的安装非常简单。macOS 用户： brew install zola</code></pre> Linux 用户可以从 GitHub Releases</a> 下载静态二进制文件： # 以 x86_64 Linux 为例 wget https://github.com/getzola/zola/releases/latest/download/zola-x86_64-unknown-linux-gnu.tar.gz tar xzf zola-x86_64-unknown-linux-gnu.tar.gz sudo mv zola /usr/local/bin/</code></pre> 验证安装： zola --version</code></pre>初始化项目</a> </h2> zola init my-blog cd my-blog</code></pre> 这条命令会生成一个基本的目录结构： my-blog/ ├── config.toml # 站点配置 ├── content/ # 文章内容 (Markdown) ├── templates/ # Tera 模板 ├── static/ # 静态资源 ├── sass/ # SCSS 文件 └── themes/ # 主题（可选）</code></pre> 注意：Zola 默认生成 config.toml</code>，但我个人习惯将其命名为 zola.toml</code>。实际上 Zola 会同时查找 config.toml</code> 和 zola.toml</code>。 </blockquote> 配置站点</a> </h2> 编辑 zola.toml</code>，填入基本信息： base_url = "https://your-domain.com" title = "我的博客" description = "记录技术与生活" default_language = "zh" taxonomies = [ { name = "tags", feed = true }, ] compile_sass = true [extra] author = "your-name"</code></pre> 配置项说明： base_url</code> — 站点的最终部署 URL，用于生成 RSS 和 sitemap。</li> taxonomies</code> — 分类法，这里定义了「标签」分类。</li> compile_sass</code> — 开启 SCSS 编译。</li> </ul> 编写模板</a> </h2> Zola 使用 Tera 模板引擎。这是博客的最小模板集： base.html — 基础骨架</a> </h3> <!DOCTYPE html> <html lang="{{ lang }}"> <head> <meta charset="UTF-8"> <title>{% block title %}LLS Blog{% endblock %}</title> <link rel="stylesheet" href="/style.css"> </head> <body> <header> <nav> <a href="/" class="site-title">LLS Blog</a> </nav> </header> <main>{% block content %}{% endblock %}</main> </body> </html></code></pre>index.html — 首页</a> </h3> 首页展示最近的文章列表。通过 get_section</code> 获取博客分区内容，然后用循环显示最新的 5 篇文章。 page.html — 文章页</a> </h3> 文章页使用 page.content</code> 来渲染 Markdown 转换后的 HTML。所有 Markdown 内容通过 | safe</code> 过滤器标记为安全的 HTML。 创建第一篇文章</a> </h2> 在 content/blog/</code> 下创建 .md</code> 文件，文件头 (front matter) 使用 TOML 格式： +++ title = "我的第一篇文章" date = 2026-01-01 description = "这是一篇示例文章" [taxonomies] tags = ["hello", "blog"] +++ 文章内容写在这里…</code></pre> Zola 会根据文件名生成永久链接，zola-blog-setup-guide.md</code> 的链接就是 /blog/zola-blog-setup-guide/</code>。 构建与预览</a> </h2> # 启动开发服务器（带热重载） zola serve # 构建生产版本 zola build</code></pre> zola serve</code> 会在 http://127.0.0.1:1111</code> 启动一个开发服务器，任何文件修改都会自动触发重建。 zola build</code> 将生成的静态文件输出到 public/</code> 目录，这个目录可以直接上传到任何静态托管服务。 集成 Pagefind 搜索</a> </h2> Pagefind</a> 是一个静态搜索库，专门为静态站点设计，支持中日韩文字。与 Zola 结合使用非常完美。 安装： npm install -g pagefind</code></pre> 每次构建后生成搜索索引： zola build npx pagefind --site public</code></pre> Pagefind 会分析 public/</code> 目录中的 HTML 文件，生成搜索索引。在前端，你只需引入它们的 JS 和 CSS 即可添加搜索框。 关于 Pagefind 的更多细节，我会在后续文章中详细介绍。 部署</a> </h2> 部署方式有很多种选择： 自托管 — 用 Nginx 或 Caddy 指向 public/</code> 目录</li> GitHub Pages — 推送到 gh-pages</code> 分支</li> Netlify / Vercel — 连接 git 仓库，设置构建命令为 zola build</code></li> Cloudflare Pages — 类似 Netlify，但有全球 CDN</li> </ul> 我的选择是自托管到自己的服务器上，用 Caddy 做反向代理并自动配置 HTTPS。 结语</a> </h2> Zola 是我目前用过最顺手的静态站点生成器。它不需要复杂的构建管道，不需要几十个依赖包，一个二进制文件就能搞定一切。 如果你正在寻找一个轻量、快速、可靠的博客方案，不妨试试 Zola。本博客的完整代码可以在我的 Gitea</a> 上查看。 下一篇我会写如何配置 Zola 的主题和自定义域名，敬请期待。

博客

记一次 TortoiseGit SSH 认证失败的排查与修复

环境</a> </h2> 远端：自托管 Gitea，端口 2222，SSH 协议</li> 客户端：Windows 11，TortoiseGit，OpenSSH</li>

给 Zola 博客添加中文全文搜索

给 Zola 博客换上 serene 主题

选主题</a> </h2> Zola 官方市场有 120+ 个主题。我的筛选条件：</p> 文档类风格</strong>：左侧导航 + 内容区 + 右侧目录</li> 维护活跃</strong>：最近一年内有提交</li>

使用 Zola 搭建静态博客