开发问题总结

本文档总结了最近几天在开发个人主页和博客系统过程中遇到的主要问题及解决方案。

一、博客文章显示问题

问题描述

博客文章创建后无法在网站上显示。

原因分析

文章 Front Matter 中的 date 字段设置为未来日期（如 2025-11-19），Hugo 默认不会发布未来日期的文章。

解决方案

将文章日期修改为当前或过去的日期：

1

date: 2025-01-19T20:00:00+08:00

经验教训

  • Hugo 默认不发布未来日期的文章，这是为了支持定时发布功能
  • 创建文章时务必检查日期设置
  • 如需定时发布，应使用 Hugo 的 publishDate 字段

二、主页布局问题

问题描述

  1. 音乐播放器歌词遮盖了备案号
  2. 备案号显示在右下角，未居中
  3. 备案号文字颜色太暗，看不清
  4. 备案号和 PowerBy 重叠在同一行

原因分析

CSS 定位和层级问题：

  • 音乐播放器使用 position: fixed 且 z-index 较高
  • 备案号区域未正确设置定位和层级
  • 文字颜色对比度不足

解决方案

多次迭代调整 CSS：

  1. 调整音乐播放器位置：
1
2
3
4
5

#aplayer.aplayer-fixed {
    position: fixed;
    bottom: 110px; /* 为备案号留出空间 */
    z-index: 10000;
}
  1. 备案号区域居中：
1
2
3
4
5
6

.remark {
    left: 50%;
    transform: translateX(-50%);
    width: min(90%, 560px);
    text-align: center;
}
  1. 使用块级元素确保换行：
1
2

<div class="remark-line">备案号内容</div>
<div class="remark-line">PowerBy 内容</div>
  1. 调整文字颜色和样式：
1
2
3
4
5

.remark-line {
    color: rgba(255, 255, 255, 0.9);
    font-weight: 500;
    letter-spacing: 0.5px;
}

经验教训

  • 固定定位元素需要考虑层级关系
  • 居中布局使用 left: 50% + transform: translateX(-50%) 更可靠
  • 文字颜色需要考虑背景对比度
  • 多次迭代调试是正常的开发过程

三、IIS 部署和 SSL 证书问题

问题描述

  1. HTTPS 访问出现 ERR_CONNECTION_RESET 错误
  2. 证书更新后问题依然存在
  3. 本地测试正常，但公网访问失败

排查过程

  1. 检查证书是否包含两个域名（yeyubaka.top 和 www.yeyubaka.top）- 确认正常
  2. 检查端口 443 是否监听 - netstat -ano | findstr :443 显示正常
  3. 使用 Test-NetConnection 测试外部连接 - 连接正常
  4. 使用 curl 测试 - 本地可以返回 HTML

最终决策

由于 IIS 配置复杂且问题难以定位，决定切换到 Caddy 服务器。

经验教训

  • IIS 的 SSL 配置相对复杂
  • 网络问题可能涉及多个层面（防火墙、路由、证书链等）
  • 有时切换技术栈是更高效的选择

四、Caddy 服务器部署

问题描述

切换到 Caddy 后，博客页面可以访问，但出现以下问题：

  1. 博客 CSS 和 JS 文件 404
  2. 静态资源路径不正确

原因分析

Caddy 的路由配置问题：

  • 使用 handle /blog* 时，Caddy 会在 C:/web/home/blog/blog/ 查找文件
  • 需要使用 handle_path 自动去掉 /blog 前缀

解决方案

修改 Caddyfile 配置：

1
2
3
4
5

# 使用 handle_path 自动去掉 /blog 前缀
handle_path /blog* {
    root * C:/web/home/blog
    file_server
}

经验教训

  • handle 和 handle_path 的区别很重要
  • handle_path 会自动去掉匹配的前缀，适合子目录部署
  • 路由顺序很重要，更具体的路由应该放在前面

五、评论系统部署问题

问题 1：502 Bad Gateway

问题描述

评论提交时出现 502 Bad Gateway 错误。

原因分析

  1. 评论服务器监听地址问题：默认监听 0.0.0.0，但 Caddy 连接 localhost 可能失败
  2. Node.js 依赖未安装：服务器上缺少 express 模块

解决方案

  1. 修改监听地址：
1
2
3

app.listen(PORT, '127.0.0.1', () => {
    // 明确监听 127.0.0.1
});
  1. 安装依赖：
1
2

cd C:\web\comments
npm install express

问题 2：SSL 协议错误

问题描述

前端使用 HTTPS，但评论 API 使用 HTTP，导致混合内容错误。

原因分析

  • 主站使用 HTTPS：https://yeyubaka.top
  • 评论 API 使用 HTTP：http://localhost:3001
  • 浏览器阻止混合内容请求

解决方案

配置 Caddy 反向代理，将 HTTPS 请求转发到 HTTP 后端：

1
2
3

handle /api/comments* {
    reverse_proxy localhost:3001
}

前端配置使用相对路径：

1
2

[params.comments]
  apiUrl = "https://yeyubaka.top"  # 不带端口

经验教训

  • 生产环境应该统一使用 HTTPS
  • 反向代理是解决混合内容问题的标准方案
  • 前端 API 地址应该使用相对路径或完整 HTTPS 地址

六、博客发布工具部署问题

问题 1：PowerShell 脚本编码错误

问题描述

运行 start-publisher-server.ps1 时出现字符串终止符错误。

错误信息

1
2

字符串缺少终止符: "。
语句块或类型定义中缺少右"}"。

原因分析

PowerShell 脚本中的中文字符编码问题，Windows 服务器可能使用不同的编码格式。

解决方案

将脚本改为英文版本，避免编码问题：

1
2

# 改为英文提示信息
Write-Host "Press Ctrl+C to stop the server" -ForegroundColor Yellow

问题 2：Cannot GET /publisher/blog-publisher.html

问题描述

访问发布工具页面时出现 404 错误。

原因分析

  1. 静态文件服务路径配置错误：Express 在 C:\web\publisher\ 查找文件
  2. Caddy 路由配置问题：使用 handle 而不是 handle_path

解决方案

  1. 修改 Express 静态文件路径：
1
2

const HOME_DIR = path.join('C:', 'web', 'home');
app.use(express.static(HOME_DIR));
  1. 修改 Caddyfile 使用 handle_path：
1
2
3

handle_path /publisher* {
    reverse_proxy localhost:3002
}

经验教训

  • PowerShell 脚本在 Windows 服务器上可能有编码问题，使用英文更安全
  • Express 静态文件服务需要正确配置根目录
  • Caddy 的 handle_path 和 handle 区别要理解清楚

七、文件同步和部署流程

问题描述

需要明确哪些文件需要上传到服务器，以及如何同步。

解决方案

创建了多个同步脚本和文档：

  1. 主页文件同步：sync-homepage.ps1

    • 同步 index.html、about.html、resume.html、resume.pdf、assets/ 等

  2. 博客文件同步：sync-comments-local-build.ps1

    • 本地构建 Hugo 博客
    • 同步构建后的 public/ 目录到服务器

  3. 一键部署：deploy-blog.ps1

    • 自动构建并同步博客

  4. 手动上传清单：MANUAL_UPLOAD_CHECKLIST.md

    • 详细列出需要上传的文件

经验教训

  • 自动化脚本可以大大减少部署错误
  • 文档化部署流程很重要
  • 区分源文件和构建文件，只上传构建结果

八、IP 地理位置解析

问题描述

评论系统需要记录评论者的 IP 地址并解析地理位置。

解决方案

使用第三方 IP 地理位置 API：

  1. 主要使用 ip-api.com（支持中文）
  2. 备用使用 ipapi.co
  3. 中国 IP 显示省份，其他国家显示国家

实现要点

1
2
3
4
5
6
7
8
9

async function getIpLocation(ip) {
    if (ip === '::1' || ip === '127.0.0.1') {
        return '本地';
    }
    
    // 尝试使用 ip-api.com
    const response = await fetch(`${IP_API_URL}${ip}?lang=zh-CN`);
    // 处理响应...
}

经验教训

  • 免费 API 可能有速率限制
  • 需要处理 API 失败的情况
  • 本地 IP 需要特殊处理

九、Caddy 配置优化

问题描述

需要配置多个路由和反向代理，确保所有功能正常工作。

最终配置结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

yeyubaka.top, www.yeyubaka.top {
    # 1. 评论 API（最优先）
    handle /api/comments* {
        reverse_proxy localhost:3001
    }
    
    # 2. 发布工具（使用 handle_path）
    handle_path /publisher* {
        reverse_proxy localhost:3002
    }
    
    # 3. 博客（使用 handle_path）
    handle_path /blog* {
        root * C:/web/home/blog
        file_server
    }
    
    # 4. 主页和其他路径
    handle {
        root * C:/web/home
        file_server
    }
}

经验教训

  • 路由顺序很重要，更具体的路由应该在前
  • handle_path 适合子目录部署
  • 反向代理配置要明确监听地址

十、开发工作流程优化

问题描述

需要建立清晰的开发、构建、部署流程。

解决方案

建立了以下工作流程：

  1. 本地开发

    • 使用 hugo server -D 预览
    • 使用 blog-publisher.html 创建文章

  2. 本地构建

    1
2

    cd blog
hugo --minify --baseURL "https://yeyubaka.top/blog/"

  3. 部署到服务器

    1

    .\deploy-blog.ps1  # 一键构建并部署

  4. 服务器端服务

    • 评论服务器：C:\web\comments\
    • 发布工具服务器：C:\web\publisher\
    • 网站文件：C:\web\home\

经验教训

  • 本地构建可以减少服务器依赖
  • 自动化脚本提高效率
  • 清晰的目录结构便于管理

总结

主要技术栈

  • 前端：HTML/CSS/JavaScript
  • 博客：Hugo + PaperMod 主题
  • 服务器：Caddy
  • 后端服务：Node.js + Express
  • 部署：PowerShell 脚本

关键决策

  1. 从 IIS 切换到 Caddy（简化 SSL 配置）
  2. 本地构建，服务器只部署静态文件
  3. 使用反向代理解决 HTTPS/HTTP 混合问题
  4. 创建自动化部署脚本

最佳实践

  1. 使用版本控制管理代码
  2. 文档化部署流程
  3. 自动化重复操作
  4. 测试后再部署
  5. 保留备份

待改进点

  1. 添加身份验证（发布工具和评论管理）
  2. 优化图片加载和压缩
  3. 添加文章编辑功能
  4. 实现自动备份
  5. 监控和日志系统

参考资料

  • Hugo 官方文档：https://gohugo.io/
  • Caddy 官方文档：https://caddyserver.com/docs/
  • PaperMod 主题：https://github.com/adityatelange/hugo-PaperMod
  • Express.js 文档：https://expressjs.com/

文档创建时间：2025-01-20 最后更新：2025-01-20