hexo-deploy/doc/test_guide/v0.0.3/TESTING_GUIDE_v0.0.3.md

Docker Hexo Static Blog v0.0.3 - 完整测试指南

📅 最新更新: 2025年5月30日 - 所有 Windows 和 Linux 测试脚本已完成路径修正，现在支持从任意目录执行，具有更好的可移植性和稳定性。Linux 平台同步实现了与 Windows 平台相同的路径修正改进。

概述

本测试指南提供了基于实际测试脚本框架的完整测试流程，支持两个测试平台：

• Windows 11 + Docker Desktop (使用 PowerShell 测试套件)
• N305 NAS + Linux Docker (使用 Bash 测试套件)

v0.0.3 版本主要新特性

本版本重点改进了日志管理和权限控制：

• ✅ 定期日志轮转功能 - 每30分钟自动检查日志大小
• ✅ 修复 Git Hook 日志权限 - 确保 hexo 用户可以写入部署日志
• ✅ 增强的日志管理 - 智能备份和旧日志清理
• ✅ 改进的错误处理 - 更详细的日志记录和错误恢复
• ✅ 权限动态管理 - 自动修复容器内文件权限问题

测试环境要求

测试环境要求

Windows 11 测试环境

• 操作系统: Windows 11 专业版或企业版
• Docker: Docker Desktop 4.15+ (支持 Linux 容器)
• PowerShell: PowerShell 5.1+ 或 PowerShell Core 7+
• 内存: 至少 4GB 可用内存
• 磁盘: 至少 10GB 可用磁盘空间
• 网络: 端口 8888 和 2222 可用 (默认端口已更新)
• 权限: 管理员权限或 Docker 使用权限

端口更新: 默认 HTTP 端口已从 8080 更新为 8888，避免常见的端口冲突

N305 NAS Linux 测试环境

• 操作系统: Linux (Ubuntu 20.04+, Debian 11+, 或兼容系统)
• Docker: Docker Engine 20.10+
• Shell: Bash 4.0+
• 内存: 至少 2GB 可用内存
• 磁盘: 至少 5GB 可用磁盘空间
• 权限: SSH 访问权限和 sudo 权限

自动化测试框架

本项目提供了完整的自动化测试框架，包含以下测试脚本：

Windows PowerShell 测试套件

位置：test/v0.0.3/windows/

• start.ps1 - 完整测试套件启动脚本，支持一键测试
• build_test.ps1 - Docker 镜像构建测试
• run_test.ps1 - 容器运行和基础功能测试
• functional_test.ps1 - HTTP/SSH/健康检查等功能测试
• log_rotation_test.ps1 - v0.0.3 新增的日志轮转功能测试
• cleanup_test.ps1 - 测试环境清理
• test_paths.ps1 - 路径验证工具脚本（新增）
• README.md - 详细使用说明文档（新增）
• PATH_FIXES_REPORT.md - 路径修正报告（新增）

重要更新: 所有 Windows 测试脚本已完成路径修正，现在支持从任意目录执行，并确保所有文件操作在正确的测试目录内进行。

路径修正改进

• ✅ 工作目录自动切换: 所有脚本现在自动切换到脚本所在目录
• ✅ 相对路径标准化: Dockerfile 路径、日志目录、测试数据目录统一使用相对路径
• ✅ PowerShell 语法修正: param() 块位置已修正，确保参数正确传递
• ✅ 卷挂载路径修正: Docker 卷挂载使用正确的绝对路径
• ✅ SSH 密钥路径统一: 所有测试中的 SSH 密钥路径已统一

Linux Bash 测试套件

位置：test/v0.0.3/linux/

• start.sh - 完整测试套件启动脚本，支持一键测试
• build_test.sh - Docker 镜像构建测试
• run_test.sh - 容器运行和基础功能测试
• functional_test.sh - HTTP/SSH/健康检查等功能测试
• log_rotation_test.sh - v0.0.3 新增的日志轮转功能测试
• cleanup_test.sh - 测试环境清理
• test_paths.sh - 路径验证和环境检查工具 (新增)
• README.md - Linux 测试套件详细使用说明 (新增)
• PATH_FIXES_REPORT.md - 路径修正完成报告 (新增)

路径修正改进 (Linux)

• ✅ 脚本目录自动获取: 所有脚本现在使用 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
• ✅ 工作目录自动切换: 通过 cd "$SCRIPT_DIR" 确保工作目录一致
• ✅ 相对路径标准化: Dockerfile 路径、日志目录、测试数据目录统一使用相对路径
• ✅ 卷挂载路径修正: Docker 卷挂载使用正确的绝对路径
• ✅ SSH 密钥路径统一: 所有测试中的 SSH 密钥路径已统一
• ✅ 日志目录本地化: 从 /tmp 迁移到脚本本地目录
• ✅ 端口配置更新: HTTP 端口从 8080 更新为 8888

快速开始

Windows 环境一键测试

# 方式1: 从测试目录运行 (推荐)
cd "c:\Users\Unbal\Desktop\dockerfiledir\test\v0.0.3\windows"
.\start.ps1

# 方式2: 从任意目录运行 (路径修正后支持)
& "c:\Users\Unbal\Desktop\dockerfiledir\test\v0.0.3\windows\start.ps1"

# 或使用自定义参数
.\start.ps1 -Tag "hexo-test:v0.0.3" -HttpPort 8888 -SshPort 2222

# 验证路径配置 (新增功能)
.\test_paths.ps1

Linux 环境一键测试

# 方式1: 从测试目录运行 (推荐)
cd "/path/to/dockerfiledir/test/v0.0.3/linux"

# 设置执行权限
chmod +x *.sh

# 运行完整测试套件
./start.sh

# 方式2: 从任意目录运行 (路径修正后支持)
"/path/to/dockerfiledir/test/v0.0.3/linux/start.sh"

# 或使用自定义参数
./start.sh --clean-start

# 验证路径配置 (新增功能)
./test_paths.sh

Windows 11 Docker Desktop 测试

方法一：一键自动化测试（推荐）

使用完整的自动化测试套件，包含构建、运行、功能验证、日志轮转测试等：

# 方式1: 从测试目录运行 (推荐)
cd "c:\Users\Unbal\Desktop\dockerfiledir\test\v0.0.3\windows"
.\start.ps1

# 方式2: 从任意目录运行 (路径修正后支持)
& "c:\Users\Unbal\Desktop\dockerfiledir\test\v0.0.3\windows\start.ps1"

# 使用自定义参数运行测试
.\start.ps1 -Tag "hexo-test:v0.0.3" -HttpPort 8888 -SshPort 2222

# 运行测试后自动清理
.\start.ps1 -CleanupAfter

# 跳过某些测试阶段
.\start.ps1 -SkipBuild -SkipLogRotation

# 验证路径配置 (新增)
.\test_paths.ps1

方法二：分步测试

如果需要分步执行或调试特定功能，可以单独运行各个测试脚本：

1. 构建测试 (build_test.ps1)

# 基础构建测试
.\build_test.ps1

# 使用自定义参数构建
.\build_test.ps1 -Tag "my-hexo:test" -Platform "linux/amd64"

# 注意：脚本现在会自动切换到正确目录，确保 Dockerfile 路径正确

2. 运行测试 (run_test.ps1)

# 基础运行测试
.\run_test.ps1

# 使用自定义参数 (默认端口已更新为 8888)
.\run_test.ps1 -Tag "my-hexo:test" -HttpPort 8888 -SshPort 2222 -ContainerName "my-hexo-test"

# 注意：卷挂载路径已修正，使用正确的绝对路径

3. 功能测试 (functional_test.ps1)

# 完整功能测试：HTTP、SSH、健康检查
.\functional_test.ps1

# 测试指定容器 (默认端口已更新)
.\functional_test.ps1 -ContainerName "my-hexo-test" -HttpPort 8888 -SshPort 2222

# 注意：SSH 密钥路径已统一，自动使用正确的绝对路径

4. 日志轮转测试 (log_rotation_test.ps1) - v0.0.3 新功能

# 测试日志轮转功能
.\log_rotation_test.ps1

# 测试指定容器的日志轮转
.\log_rotation_test.ps1 -ContainerName "my-hexo-test"

# 注意：SSH 密钥路径已修正，确保测试的稳定性和可移植性

5. 清理测试 (cleanup_test.ps1)

# 清理测试环境
.\cleanup_test.ps1

# 清理指定容器和镜像
.\cleanup_test.ps1 -ContainerName "my-hexo-test" -ImageTag "my-hexo:test"

start.ps1 完整参数说明

# 完整参数列表
.\start.ps1 `
    -SkipBuild          # 跳过构建阶段
    -SkipFunctional     # 跳过功能测试阶段
    -SkipLogRotation    # 跳过日志轮转测试阶段
    -CleanupAfter       # 测试完成后自动清理环境
    -Tag "custom:tag"   # 自定义 Docker 镜像标签
    -ContainerName "name" # 自定义容器名称
    -HttpPort 8888      # HTTP 服务端口 (默认: 8888)
    -SshPort 2222       # SSH 服务端口 (默认: 2222)

# 测试结果和日志
# 所有测试都会生成详细的日志文件在 logs/ 目录下
# 测试完成后会显示完整的测试报告

# 路径验证工具 (新增)
.\test_paths.ps1        # 验证和创建所需的目录结构

# 详细使用说明
Get-Content .\README.md # 查看详细的使用说明和故障排除指南

N305 NAS Linux 测试

方法一：一键自动化测试（推荐）

使用完整的自动化测试套件，支持完全自动化的测试流程：

# 进入 Linux 测试目录
cd "/path/to/dockerfiledir/test/v0.0.3/linux"

# 设置执行权限
chmod +x *.sh

# 运行完整测试套件（推荐）
./start.sh

# 使用清理模式运行测试（运行前清理环境）
./start.sh --clean-start

# 查看帮助信息
./start.sh --help

方法二：分步测试

如果需要分步执行或调试特定功能，可以单独运行各个测试脚本：

1. 构建测试 (build_test.sh)

# 基础构建测试
./build_test.sh

# 使用自定义参数构建
./build_test.sh "my-hexo:test" "linux/amd64"

2. 运行测试 (run_test.sh)

# 基础运行测试
./run_test.sh

# 使用自定义参数
./run_test.sh "my-hexo:test" "my-hexo-test" 8888 2222

3. 功能测试 (functional_test.sh)

# 完整功能测试：HTTP、SSH、健康检查
./functional_test.sh

# 测试指定容器
./functional_test.sh "my-hexo-test" 8888 2222

4. 日志轮转测试 (log_rotation_test.sh) - v0.0.3 新功能

# 测试日志轮转功能
./log_rotation_test.sh

# 测试指定容器的日志轮转
./log_rotation_test.sh "my-hexo-test"

5. 清理测试 (cleanup_test.sh)

# 清理测试环境
./cleanup_test.sh

# 清理指定容器和镜像
./cleanup_test.sh "my-hexo-test" "my-hexo:test"

start.sh 完整参数说明

# 基础用法
./start.sh                    # 标准测试流程
./start.sh --clean-start      # 清理后重新开始测试
./start.sh --help            # 显示帮助信息

# 测试结果和日志
# 所有测试日志保存在 /tmp/hexo-test-suite/ 目录下
# 测试完成后会显示完整的彩色测试报告
# 支持自动故障检测和详细错误报告

Linux 环境特殊配置

# 确保 Docker 服务运行
sudo systemctl start docker
sudo systemctl enable docker

# 将当前用户添加到 docker 组（避免使用 sudo）
sudo usermod -aG docker $USER
newgrp docker

# 验证 Docker 安装
docker --version
docker-compose --version

# 确保所需端口可用
sudo netstat -tlnp | grep -E ':(8888|2222)'

自动化测试框架特性

测试套件功能

1. 智能测试流程 - 自动检测前置条件，智能跳过不必要的步骤
2. 详细日志记录 - 每个测试阶段都有完整的日志记录和时间戳
3. 彩色输出显示 - 清晰的成功/失败状态指示
4. 错误自动诊断 - 测试失败时提供详细的错误分析
5. 性能指标统计 - 自动记录构建时间、启动时间、内存使用等
6. 测试报告生成 - 自动生成标准化的测试报告

测试覆盖范围

• ✅ Docker 镜像构建 - 验证 Dockerfile_v0.0.3 构建过程
• ✅ 容器启动验证 - 检查容器是否正常启动和运行
• ✅ HTTP 服务测试 - 验证 Nginx 服务和静态文件服务
• ✅ SSH 服务测试 - 验证 SSH 连接和身份验证
• ✅ 健康检查测试 - 验证 /health 端点响应
• ✅ 日志轮转测试 - v0.0.3 特有的日志管理功能
• ✅ Git 部署测试 - 验证 Git hooks 和自动部署
• ✅ 权限验证测试 - 确保文件权限和用户权限正确
• ✅ 环境清理测试 - 验证测试环境的完整清理

测试检查清单

基础功能验证

• Docker 镜像成功构建（< 5 分钟）
• 容器成功启动（< 30 秒）
• HTTP 服务响应正常（端口 8888）
• 健康检查端点 /health 返回 "OK"
• SSH 服务可连接（端口 22/2222）
• Git 仓库初始化正确
• Hexo 站点文件部署正常

v0.0.3 新功能验证

• 定期日志轮转功能正常（每30分钟检查）
• Git Hook 日志权限正确（hexo 用户可写入）
• 部署日志 /var/log/container/deployment.log 正常
• 日志文件大小控制（10MB 轮转触发）
• 旧日志文件自动清理和备份
• 时间戳日志备份文件生成

安全性验证

• 容器以非 root 用户（hexo）运行
• SSH 仅支持密钥认证（密码认证已禁用）
• 文件权限设置正确（644/755）
• 网络端口访问控制正常
• 敏感文件权限保护

性能和稳定性验证

• 容器启动时间 < 30 秒
• HTTP 响应时间 < 1 秒
• 内存使用 < 500MB
• CPU 使用率正常（< 50%）
• 日志轮转不影响服务性能
• 多次部署操作稳定无错误

故障排查指南

自动化测试框架故障排查

1. 测试脚本权限问题

# Linux 环境
chmod +x test/v0.0.3/linux/*.sh

# Windows 环境（PowerShell 执行策略）
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

2. 路径相关问题 (新增)

# Windows 环境 - 验证路径配置
cd "c:\Users\Unbal\Desktop\dockerfiledir\test\v0.0.3\windows"
.\test_paths.ps1

# 查看路径修正报告
Get-Content .\PATH_FIXES_REPORT.md

# 查看详细使用说明
Get-Content .\README.md

2. Docker 相关问题

# 检查 Docker 服务状态
docker info
docker version

# 清理 Docker 环境
docker system prune -f
docker volume prune -f

3. 端口冲突问题

# Linux 检查端口占用
netstat -tlnp | grep -E ':(8888|2222)'  # 端口已更新
sudo lsof -i :8888
sudo lsof -i :2222

# Windows 检查端口占用
netstat -ano | findstr :8888            # 端口已更新
netstat -ano | findstr :2222

4. 测试日志分析

# 查看最新测试日志
ls -la logs/ | tail -5                    # Linux
Get-ChildItem logs\ | Sort-Object LastWriteTime | Select-Object -Last 5  # Windows

# 搜索错误信息
grep -i error logs/test_suite_*.log       # Linux
Select-String -Pattern "error" -Path "logs\test_suite_*.log"  # Windows

容器运行时故障排查

1. 容器无法启动

# 检查容器日志
docker logs hexo-test-v003

# 检查镜像是否存在
docker images | grep hexo-test

# 检查 Dockerfile 语法
docker build --dry-run -f Dockerfile_v0.0.3 .

2. 服务连接失败

# 检查容器网络
docker port hexo-test-v003
docker inspect hexo-test-v003 | grep -A 10 "NetworkSettings"

# 测试容器内服务
docker exec hexo-test-v003 curl -f http://localhost/health
docker exec hexo-test-v003 netstat -tlnp

3. 日志轮转问题（v0.0.3 特有）

# 检查日志轮转配置
docker exec hexo-test-v003 cat /etc/logrotate.d/container-logs

# 手动触发日志轮转
docker exec hexo-test-v003 logrotate -f /etc/logrotate.d/container-logs

# 检查日志文件状态
docker exec hexo-test-v003 ls -la /var/log/container/

测试报告模板

基本信息

• 测试版本: Docker Hexo Static Blog v0.0.3
• 测试平台: Windows 11 / Linux
• 测试日期: {{ 测试日期 }}
• 测试人员: {{ 测试人员 }}
• Docker 版本: {{ docker --version }}

自动化测试结果

测试阶段	状态	执行时间	备注
镜像构建	✅/❌	{{ 时间 }}	{{ 备注 }}
容器启动	✅/❌	{{ 时间 }}	{{ 备注 }}
HTTP 服务	✅/❌	{{ 时间 }}	{{ 备注 }}
SSH 服务	✅/❌	{{ 时间 }}	{{ 备注 }}
功能测试	✅/❌	{{ 时间 }}	{{ 备注 }}
日志轮转	✅/❌	{{ 时间 }}	{{ 备注 }}
环境清理	✅/❌	{{ 时间 }}	{{ 备注 }}

性能指标

• 总测试时间: {{ 总时间 }}
• 镜像构建时间: {{ 构建时间 }}
• 容器启动时间: {{ 启动时间 }}
• 内存使用峰值: {{ 内存使用 }}
• HTTP 响应时间: {{ 响应时间 }}

v0.0.3 新功能测试结果

• 日志轮转功能: ✅/❌ {{ 详细说明 }}
• Git Hook 权限: ✅/❌ {{ 详细说明 }}
• 部署日志管理: ✅/❌ {{ 详细说明 }}
• 权限动态修复: ✅/❌ {{ 详细说明 }}

发现的问题

1. {{ 问题描述 1 }}
2. {{ 问题描述 2 }}
3. {{ 问题描述 3 }}

改进建议

1. {{ 改进建议 1 }}
2. {{ 改进建议 2 }}
3. {{ 改进建议 3 }}

---

总结

本测试指南基于项目中实际的自动化测试框架编写，提供了：

主要特性

• ✅ 完全自动化 - 一键执行完整测试流程
• ✅ 跨平台支持 - Windows PowerShell 和 Linux Bash 双平台
• ✅ 智能诊断 - 自动错误检测和详细报告
• ✅ 详细日志 - 完整的测试过程记录
• ✅ 灵活配置 - 支持自定义参数和选择性测试
• ✅ 路径修正完成 - 所有 Windows 和 Linux 测试脚本已完成路径修正 (2025年5月)

v0.0.3 测试脚本更新内容 (2025年5月30日)

Windows PowerShell 测试套件改进

1. 路径修正: 所有 Windows PowerShell 测试脚本完成路径修正
2. 工作目录标准化: 脚本自动切换到正确的工作目录
3. PowerShell 语法修正: param() 块位置已修正
4. 卷挂载路径修正: Docker 卷挂载使用正确的绝对路径
5. SSH 密钥路径统一: 统一所有测试中的 SSH 密钥路径处理
6. 端口更新: 默认 HTTP 端口从 8080 更新为 8888
7. 新增工具: 添加 test_paths.ps1 路径验证工具

Linux Bash 测试套件改进 (新增)

1. 路径修正: 所有 Linux Bash 测试脚本完成路径修正
2. 脚本目录自动获取: 使用 SCRIPT_DIR 变量统一路径处理
3. 工作目录标准化: 通过 cd "$SCRIPT_DIR" 确保一致性
4. 卷挂载路径修正: Docker 卷挂载使用正确的绝对路径
5. SSH 密钥路径统一: 统一所有测试中的 SSH 密钥路径处理
6. 日志目录本地化: 从 /tmp 迁移到脚本本地目录
7. 端口配置更新: HTTP 端口从 8080 更新为 8888
8. 新增工具: 添加 test_paths.sh 路径验证工具和详细文档
9. 新增工具脚本:
   • test_paths.ps1 - 路径验证工具
   • README.md - 详细使用说明
   • PATH_FIXES_REPORT.md - 路径修正完成报告

使用建议

1. 日常开发测试 - 使用一键测试脚本快速验证
2. 详细功能验证 - 使用分步测试脚本深入调试
3. 持续集成 - 集成到 CI/CD 流程中自动化验证
4. 生产部署前 - 运行完整测试套件确保稳定性
5. 路径验证 - 使用 test_paths.ps1 验证测试环境配置

测试覆盖

本测试框架全面覆盖了 Docker Hexo Static Blog v0.0.3 的所有核心功能，特别是新版本的日志轮转和权限管理功能，确保在不同环境中的稳定性和可靠性。

通过使用这个自动化测试框架，可以大大提高测试效率，减少人为错误，并确保每次测试的一致性和完整性。经过路径修正后，Windows 测试脚本现在具有更好的可移植性和可靠性。