UnbalancedCat/hexo-deploy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.0.3 published

Browse Source
This commit is contained in:
包焕垲
2025-06-02 11:27:10 +08:00
commit dca4f11e0d
61 changed files with 16453 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

390
README.md Normal file
View File

@@ -0,0 +1,390 @@
# Hexo Blog Docker Containerization Solution
**Project Status**: ✅ Production Ready | **Latest Version**: v0.0.3 (Stable) | **Updated**: May 30, 2025
An enterprise-grade Hexo blog Docker containerization solution providing SSH access, Nginx web service, Git auto-deployment, and comprehensive security protection. Version v0.0.3 is a stable version focusing on core feature reliability and ease of use.
> 📖 **Quick Start**: [30-Second Deployment Guide](README_QUICK_START_SIMPLE.md)
> 📖 **Complete Guide**: [Detailed Deployment Documentation](README_QUICK_START_COMPLETE.md)
> 📖 **Chinese Documentation**: [README_zh.md](README_zh.md)
> 📋 **Version History**: [Comprehensive Version Summary](doc/COMPREHENSIVE_VERSION_SUMMARY.md)
## 🚀 Quick Start
### Instant Deployment (30 seconds)
```powershell
# Build and start stable version
docker build -f Dockerfile_v0.0.3 -t hexo-blog:stable . && `
docker run -d --name hexo-blog-stable --restart unless-stopped -p 8080:80 -p 2222:22 hexo-blog:stable && `
Write-Host "🎉 Deployment Complete! Visit: http://localhost:8080" -ForegroundColor Green
```
### Access Verification
- 🌐 **Web Interface**: http://localhost:8080
- 💚 **Health Check**: http://localhost:8080/health
- 📊 **Container Status**: `docker ps | findstr hexo-blog`
## ✨ Core Features
### v0.0.3 Stable Features ✅
- 🛡️ **SSH Key Authentication** - Secure remote access and deployment
- 🌐 **Nginx Web Service** - High-performance static file serving
- 🔄 **Git Auto Deployment** - Push-to-update automation workflow
- 💚 **Health Monitoring** - `/health` endpoint real-time status monitoring
- 🐳 **Docker Optimized** - Streamlined image, fast startup
- 📝 **Smart Log Management** - Including log rotation and size control.
## 📚 Complete Documentation Index
| Document Type | File Link | Purpose | Status |
|---------------|-----------|---------|--------|
| **Quick Deploy** | [README_QUICK_START_SIMPLE.md](README_QUICK_START_SIMPLE.md) | 30-second deployment | ✅ |
| **Complete Guide** | [README_QUICK_START_COMPLETE.md](README_QUICK_START_COMPLETE.md) | Detailed configuration and troubleshooting | ✅ |
| **Version Summary** | [doc/COMPREHENSIVE_VERSION_SUMMARY.md](doc/COMPREHENSIVE_VERSION_SUMMARY.md) | Complete version history and comparison | ✅ |
| **Production Deploy** | [doc/summary/v0.0.3/](doc/summary/v0.0.3/) | v0.0.3 production environment deployment | ✅ |
| **Test Guide** | [test/v0.0.3/windows/README.md](test/v0.0.3/windows/README.md) | v0.0.3 testing and verification | ✅ |
## 🧪 Testing and Verification
### Automated Testing (v0.0.3)
```powershell
# v0.0.3 stable version comprehensive testing
cd "test\v0.0.3\windows"
.\run_test.ps1
.\functional_test.ps1
.\log_rotation_test.ps1
.\cleanup_test.ps1
# Testing includes:
# ✅ Container health check
# ✅ Web service functionality
# ✅ SSH key authentication
# ✅ Git deployment workflow
# ✅ Log rotation mechanism
```
### Manual Verification
```powershell
# v0.0.3 stable version verification
docker ps | findstr hexo-blog # Container status
curl http://localhost:8080/health # Health check
ssh -i .\ssh-keys\your_private_key_file -p 2222 hexo@localhost # SSH connection (use your key file)
git push docker main # Git deployment
# Check deployment log
docker exec hexo-blog-stable cat /var/log/container/deployment.log
```
## 🔧 Environment Variables Configuration
### SSH Configuration
- `SSH_PORT` - SSH port (default: 22)
- `PERMIT_ROOT_LOGIN` - Allow root login (default: no)
- `PUID` - hexo user ID (default: 1000)
- `PGID` - hexo group ID (default: 1000)
### Nginx Configuration
- `HTTP_PORT` - HTTP port (default: 80)
- `NGINX_USER` - Nginx worker process user (default: hexo)
- `NGINX_WORKERS` - Number of worker processes (default: auto)
- `NGINX_CONNECTIONS` - Worker connections (default: 1024)
- `SERVER_NAME` - Server name (default: localhost)
- `WEB_ROOT` - Web root directory (default: /home/www/hexo)
### System Configuration
- `TZ` - Timezone (default: Asia/Shanghai)
## 📦 Deployment Guide
### Build Images
```powershell
# v0.0.3 stable version build
docker build -f Dockerfile_v0.0.3 -t hexo-blog:v0.0.3 .
# Custom build arguments
docker build -f Dockerfile_v0.0.3 -t hexo-blog:v0.0.3 `
--build-arg PUID=1001 `
--build-arg PGID=1001 `
--build-arg TZ=Asia/Shanghai `
.
# View detailed build process
docker build -f Dockerfile_v0.0.3 -t hexo-blog:v0.0.3 --progress=plain .
```
### Basic Deployment
```powershell
# v0.0.3 stable version - simple deployment
docker run -d `
--name hexo-blog-stable `
-p 2222:22 `
-p 8080:80 `
-v ${PWD}\hexo-data:/home/www/hexo `
-v ${PWD}\ssh-keys:/home/hexo/.ssh `
-v ${PWD}\container-logs:/var/log/container `
hexo-blog:v0.0.3
```
### Production Environment Deployment
```powershell
# v0.0.3 stable version - production configuration
docker run -d `
--name hexo-blog-prod `
--restart unless-stopped `
-p 2222:22 `
-p 8080:80 `
-e SSH_PORT=22 `
-e HTTP_PORT=80 `
-e PUID=1001 `
-e PGID=1001 `
-e SERVER_NAME=yourdomain.com `
-e NGINX_WORKERS=auto `
-e NGINX_CONNECTIONS=1024 `
-v ${PWD}\hexo-data:/home/www/hexo `
-v ${PWD}\ssh-keys:/home/hexo/.ssh `
-v ${PWD}\container-logs:/var/log/container `
-v ${PWD}\nginx-logs:/var/log/nginx `
hexo-blog:v0.0.3
```
### Docker Compose Deployment
```yaml
version: '3.8'
services:
hexo-blog:
build:
context: .
dockerfile: Dockerfile_v0.0.3
args:
- PUID=1001
- PGID=1001
- TZ=Asia/Shanghai
container_name: hexo-blog-stable
restart: unless-stopped
ports:
- "2222:22"
- "8080:80"
environment:
- PUID=1001
- PGID=1001
- SERVER_NAME=yourdomain.com
- NGINX_WORKERS=auto
- NGINX_CONNECTIONS=1024
- TZ=Asia/Shanghai
volumes:
- ./hexo-data:/home/www/hexo
- ./ssh-keys:/home/hexo/.ssh
- ./git-repo:/home/hexo/hexo.git
- ./logs/container:/var/log/container
- ./logs/nginx:/var/log/nginx
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 15s
```
## 🛡️ Security Features
### v0.0.3 Security Features
- ✅ **SSH Password Authentication Disabled** - Key-based authentication only
- ✅ **Root Login Disabled** - Principle of least privilege
- ✅ **Nginx Non-root Execution** - hexo user privilege isolation
- ✅ **Security Response Headers** - CSP, X-Frame-Options, X-Content-Type-Options
- ✅ **Server Identity Hidden** - Reduced information disclosure
- ✅ **Dynamic PUID/PGID** - File permission security
## ⚡ Performance Optimization
### v0.0.3 Performance Features
- 🚀 **Gzip Compression** - Smart compression for text files
- 🚀 **Static File Caching** - Reasonable cache header settings
- 🚀 **Nginx Performance Tuning** - sendfile, tcp_nopush, tcp_nodelay
- 🚀 **Multi-stage Build** - Reduced image size
## 📊 Monitoring & Logging
### v0.0.3 Monitoring & Logging Features
- 📊 **Health Check** - `/health` endpoint, 30-second interval checks
- 📝 **Smart Log Management** - Colored output, 10MB size limit rotation, keeps last 5 log files.
- 📊 **Service Monitoring** - Basic process status monitoring, auto-restart
- 🔍 **Enhanced startup logs**: Detailed container startup process, configuration validation, and dynamic permission application
- 🔄 **Periodic log rotation**: Automatic log file rotation checks every 30 minutes with timestamped backups
## Git Deployment
The container includes a bare Git repository for easy deployment:
```bash
# On your local machine, add the container as a remote
# Replace your-server with your server's IP or hostname, and 2222 with the mapped SSH port
git remote add deploy ssh://hexo@your-server:2222/home/hexo/hexo.git
# Deploy your Hexo site (ensure your SSH key is added to the agent or specified)
git push deploy main
```
The post-receive hook will automatically checkout files to `/home/www/hexo`, set proper permissions, and log detailed deployment information including file counts and total size to `/var/log/container/deployment.log`.
## Volumes
| Volume Path in Container | Description | Purpose |
|--------------------------|-------------|---------|
| `/home/www/hexo` | Hexo site files | Static website content |
| `/home/hexo/.ssh` | SSH keys and configuration | SSH authentication (mount your `authorized_keys`) |
| `/home/hexo/hexo.git` | Git repository for deployment | Automated deployment (managed by container) |
| `/var/log/container` | Container service logs | Application logging (e.g., `deployment.log`) |
| `/var/log/nginx` | Nginx access and error logs | Web server logging |
## Port Mapping
| Container Port | Host Port (Example) | Protocol | Description |
|----------------|---------------------|----------|-------------|
| 22 | 2222 | TCP | SSH server |
| 80 | 8080 | TCP | HTTP web server |
## Troubleshooting
### Container won't start
```powershell
# Check container logs
docker logs hexo-blog-stable # Or your container name
# Check health status
docker inspect hexo-blog-stable | Select-String Health -A 10
# Check for port conflicts on the host
netstat -an | findstr "8080" # Check for your HTTP port
netstat -an | findstr "2222" # Check for your SSH port
```
### SSH connection issues
```powershell
# Verify SSH key permissions on your local machine (PowerShell example)
# Ensure your private key file (e.g., id_rsa) is protected
icacls .\ssh-keys\your_private_key_file # Should typically only grant access to your user
# Check authorized_keys in the container
docker exec hexo-blog-stable ls -la /home/hexo/.ssh/
docker exec hexo-blog-stable cat /home/hexo/.ssh/authorized_keys # Verify your public key is present and correct
# Check SSH service status in container
docker exec hexo-blog-stable ps aux | grep sshd
# Verbose SSH connection test from your local machine
ssh -i .\ssh-keys\your_private_key_file -p 2222 -vvv hexo@localhost
```
### Nginx issues / Web service not accessible
```powershell
# Test Nginx configuration in container
docker exec hexo-blog-stable nginx -t
# Check Nginx logs in container
docker exec hexo-blog-stable tail -f /var/log/nginx/error.log
docker exec hexo-blog-stable tail -f /var/log/nginx/access.log
# Check Nginx status in container
docker exec hexo-blog-stable ps aux | grep nginx
# Test health endpoint
curl http://localhost:8080/health
```
### Git Deployment Failures
```powershell
# Check permissions of the bare repository in the container
docker exec hexo-blog-stable ls -la /home/hexo/hexo.git/
# Check the deployment log in the container
docker exec hexo-blog-stable cat /var/log/container/deployment.log
# Test Git push with verbosity
git push deploy main -vvv
```
## Version Information
### v0.0.3 (Current Stable)
- ✅ **Smart Log Size Control**: Implemented and tested log rotation for `deployment.log` (1MB limit, keeps 5 backups).
- ✅ **SSH Stability**: Resolved SSH login failures by correcting `authorized_keys` permissions within the container post-startup.
- ✅ **Test Suite Enhancements**: Updated and validated `run_test.ps1` and `functional_test.ps1` for v0.0.3.
- ✅ **Documentation**: Updated README files to reflect v0.0.3 as the latest stable version.
- Focus on stability and core functionality.
### v0.0.2
- Enhanced security with advanced headers (CSP, Referrer-Policy)
- Intelligent log rotation with 10MB file size limit (initial implementation)
- Dynamic PUID/PGID support for proper file ownership
- Dedicated `/health` endpoint for enhanced monitoring
- Improved SSH security (MaxAuthTries, ClientAlive settings)
- Heredoc syntax for better script readability
- Minimal production image (removed vim, nodejs, npm)
- Enhanced deployment logging with detailed file tracking
- Advanced service monitoring with automatic recovery
- Smart configuration template rendering
### v0.0.1
- Implemented multi-stage Docker build
- Integrated SSH and Nginx services
- Template-based configuration system
- Colored logging output
- Automatic service monitoring and restart
- Health check functionality
- Git automated deployment support
- Security hardening configuration
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/YourFeature`)
3. Make your changes
4. Test the Docker build (`docker build -f Dockerfile_v0.0.3 -t hexo-blog:test .`)
5. Commit your changes (`git commit -m 'Add some feature'`)
6. Push to the branch (`git push origin feature/YourFeature`)
7. Submit a pull request
## File Structure
```
dockerfiledir/
├── Dockerfile_v0.0.3 # Current stable Dockerfile
├── Dockerfile_v0.0.4 # Previous development Dockerfile (archived)
├── README.md # This file (English documentation)
├── README_zh.md # Chinese documentation
├── README_QUICK_START_SIMPLE.md
├── README_QUICK_START_COMPLETE.md
├── start.sh # Main entrypoint script for the container
├── arch/ # Archived Dockerfiles (v0.0.1, v0.0.2)
├── doc/ # Additional documentation
│ ├── COMPREHENSIVE_VERSION_SUMMARY.md
│ └── ...
└── test/
└── v0.0.3/
└── windows/ # Test scripts for v0.0.3
├── run_test.ps1
├── functional_test.ps1
├── log_rotation_test.ps1
├── cleanup_test.ps1
└── README.md # Test guide for v0.0.3
```
## License
This project is open source and available under the [MIT License](LICENSE).
## 🔗 Related Resources
- 📖 **Chinese Documentation**: [README_zh.md](README_zh.md)
- 📋 **Complete Version History**: [Comprehensive Version Summary](doc/COMPREHENSIVE_VERSION_SUMMARY.md)
- 🚀 **Quick Deployment Guide**: [30-Second Deployment](README_QUICK_START_SIMPLE.md)
- 📖 **Detailed Configuration Guide**: [Complete Deployment Documentation](README_QUICK_START_COMPLETE.md)
- 🧪 **Test Guide (v0.0.3)**: [test/v0.0.3/windows/README.md](test/v0.0.3/windows/README.md)
- 📊 **Technical Documentation (v0.0.3)**: [doc/summary/v0.0.3](doc/summary/v0.0.3)
---
**Project Status**: ✅ Production Ready
**Maintenance Status**: 🔄 Actively Maintained
**Technical Support**: 📧 Via GitHub Issues
**Last Updated**: May 30, 2025