Caddy配置Typecho博客详解

一、基础配置解析

完整配置示例

blog.zhaopeng.site {
    root * /var/www/html
    php_fastcgi typecho2:9000 {
        try_files {path} {path}/index.php /index.php?{query}
        env PATH_INFO {http.path_info}
    }
    file_server
    encode gzip zstd
    @markdown path *.md
    rewrite @markdown /mdtemplate.html
    templates {
        path /mdtemplate.html
    }
    header @markdown Content-Type text/html
    header {
        X-Content-Type-Options nosniff
        X-Frame-Options SAMEORIGIN
        Referrer-Policy strict-origin-when-cross-origin
    }
}

核心功能说明

域名: blog.zhaopeng.site
根目录: /var/www/html
PHP处理器: typecho2:9000 (FastCGI)
静态文件: 由Caddy直接处理
Markdown: 自动渲染为HTML

二、配置逐行详解

站点块定义

blog.zhaopeng.site {

定义站点块，所有配置应用于此域名。Caddy自动为此域名申请HTTPS证书。

根目录设置

root * /var/www/html

设置网站根目录为/var/www/html。*表示匹配所有路径，所有请求都从该目录查找文件。

PHP处理配置

php_fastcgi typecho2:9000 {

配置PHP处理，将PHP请求转发到typecho2:9000这个PHP-FPM服务。typecho2是容器名或主机名，9000是PHP-FPM端口。

try_files {path} {path}/index.php /index.php?{query}

尝试按顺序查找文件：

{path}: 先尝试请求的原始路径
{path}/index.php: 如果是目录，尝试找index.php
/index.php?{query}: 都找不到时，转发到index.php并保留查询参数
这是Typecho伪静态的核心，实现URL重写。

env PATH_INFO {http.path_info}

设置环境变量PATH_INFO，值为请求的路径信息。某些PHP框架需要此变量处理路由。

静态文件服务

file_server

启用静态文件服务。当请求的是文件时，直接返回文件内容。

压缩配置

encode gzip zstd

启用压缩，支持gzip和zstd两种算法。浏览器自动选择支持的格式，减少传输大小。

Markdown处理

@markdown path *.md

定义名为markdown的匹配器，匹配所有以.md结尾的路径。

rewrite @markdown /mdtemplate.html

当请求匹配@markdown时，内部重写到/mdtemplate.html。浏览器地址栏不变，服务器返回模板文件。

templates {
    path /mdtemplate.html
}

对/mdtemplate.html启用模板引擎，可在HTML中嵌入Caddy模板语法。

header @markdown Content-Type text/html

对匹配@markdown的请求，设置响应头Content-Type: text/html，让浏览器将.md文件当HTML显示。

安全头配置

header {
    X-Content-Type-Options nosniff
    X-Frame-Options SAMEORIGIN
    Referrer-Policy strict-origin-when-cross-origin
}

设置安全响应头（对所有请求）：

X-Content-Type-Options nosniff: 禁止浏览器猜测MIME类型，防止XSS攻击
X-Frame-Options SAMEORIGIN: 只允许同源域名用iframe嵌入，防止点击劫持
Referrer-Policy strict-origin-when-cross-origin: 跨域请求时只发送来源域名，保护隐私

三、动静分离原理

为什么不能直接使用reverse_proxy

aaaa.zhaopeng.site {
    reverse_proxy typecho:9000
}

此配置无法访问的原因：

协议不匹配: Typecho容器的9000端口使用FastCGI协议，而非标准HTTP协议。reverse_proxy是标准HTTP反向代理，无法与FastCGI服务通信。
动静未分离: 所有请求都被无差别转发到PHP容器，静态资源无法由Caddy高效处理，增加后端压力。

正确处理方式

使用php_fastcgi指令的理由：

Caddy内置对FastCGI协议的支持
自动实现动静分离：静态文件由Caddy直接返回，PHP请求转发给后端
简化配置，不需要手动区分请求类型

请求处理流程

用户访问https://blog.zhaopeng.site时：

HTTPS证书: Caddy自动处理
路由匹配:
- 访问/style.css: file_server直接返回文件
- 访问/about: php_fastcgi转发到PHP处理
- 访问/post.md: 匹配@markdown，重写到/mdtemplate.html
压缩: 所有响应用gzip或zstd压缩
安全头: 添加配置的安全响应头

四、优化建议

精确路由匹配

@php {
    path *.php
    not path /mdtemplate.html
}
php_fastcgi @php typecho2:9000 {
    try_files {path} {path}/index.php?{query} /index.php?{query}
    env PATH_INFO {http.path_info}
}

避免PHP-FastCGI错误处理Markdown模板，只对.php文件生效。

静态资源缓存

@static {
    file
    path *.css *.js *.jpg *.png *.gif *.svg *.woff2 *.woff *.ttf *.ico
}
header @static Cache-Control "public, max-age=31536000, immutable"
file_server @static

静态文件设置1年缓存，提升加载速度。

验证文件优先处理

@acme path /.well-known/acme-challenge/*
file_server @acme

确保证书验证不受其他规则干扰。

目录隐藏

file_server {
    hide .git .env .htaccess
}

防止敏感文件被访问。

进阶优化选项

获取真实IP（使用CDN或反向代理时）:

trusted_proxies static private_ranges

日志格式优化:

log {
    output file /var/log/caddy/blog.log {
        roll_size 100mb
        roll_keep 5
    }
    format json
}

连接限流（访问量大时）:

rate_limit {
    zone dynamic {
        key {remote_host}
        events 100
        window 1m
    }
}

完整优化配置示例

blog.zhaopeng.site {
    root * /var/www/html
    
    @acme path /.well-known/acme-challenge/*
    file_server @acme
    
    @static {
        file
        path *.css *.js *.jpg *.png *.gif *.svg *.woff2 *.woff *.ttf *.ico
    }
    header @static Cache-Control "public, max-age=31536000, immutable"
    file_server @static
    
    @markdown path *.md
    rewrite @markdown /mdtemplate.html
    templates @markdown {
        path /mdtemplate.html
    }
    header @markdown Content-Type text/html
    
    @php {
        path *.php
        not path /mdtemplate.html
    }
    php_fastcgi @php typecho2:9000 {
        try_files {path} {path}/index.php?{query} /index.php?{query}
        env PATH_INFO {http.path_info}
    }
    
    file_server {
        hide .git .env .htaccess
    }
    
    encode gzip zstd
    
    header {
        X-Content-Type-Options "nosniff"
        X-Frame-Options "SAMEORIGIN"
        Referrer-Policy "strict-origin-when-cross-origin"
        
        @html path *.html
        header @html Cache-Control "no-cache, no-store, must-revalidate"
    }
}

优化效果对比

优化项	优化前	优化后
静态资源缓存	无	1年
PHP处理	所有请求	仅PHP文件
目录暴露	可能暴露敏感文件	隐藏
验证文件	可能被PHP拦截	独立处理

五、验证与调试

配置验证

caddy validate --config Caddyfile

运行与日志查看

caddy run --config Caddyfile --adapter caddyfile

查看访问日志:

tail -f /var/log/caddy/blog.log

功能测试

测试静态缓存:

curl -I https://blog.zhaopeng.site/style.css

预期看到:

Cache-Control: public, max-age=31536000

测试PHP处理:

curl -I https://blog.zhaopeng.site/index.php

测试Markdown渲染:

curl -I https://blog.zhaopeng.site/post.md

预期看到:

Content-Type: text/html

常见问题排查

Typecho文章404: 检查try_files规则是否已正确转换
Markdown无法显示: 确认/mdtemplate.html文件存在且权限正确
PHP不工作: 检查typecho2:9000是否能连通
```
curl -I http://typecho2:9000
```
证书问题: 确保域名解析正确，80和443端口开放

六、关键要点总结

Typecho博客必须使用php_fastcgi而非reverse_proxy，因为PHP-FPM使用FastCGI协议
Caddy负责处理静态文件，PHP请求转发给后端容器，实现动静分离
root目录用于存放静态文件和证书验证文件
try_files规则是Typecho伪静态的核心配置
安全头配置是必要的安全防护措施
静态资源缓存可以显著提升性能
Markdown处理通过重写和模板引擎实现
验证文件和敏感文件需要特殊处理

文档创建日期: 2026-08-25
适用版本: Caddy 2.x

Caddy配置Typecho博客详解

Caddy配置Typecho博客详解

目录

一、基础配置解析

完整配置示例

核心功能说明

二、配置逐行详解

站点块定义

根目录设置

PHP处理配置

静态文件服务

压缩配置

Markdown处理

安全头配置

三、动静分离原理

为什么不能直接使用reverse_proxy

正确处理方式

请求处理流程

四、优化建议

精确路由匹配

静态资源缓存

验证文件优先处理

目录隐藏

进阶优化选项

完整优化配置示例

优化效果对比

五、验证与调试

配置验证

运行与日志查看

功能测试

常见问题排查

六、关键要点总结

添加新评论

分类