Docker 化部署 Typecho 完整指南

概述

Typecho 是一款轻量级 PHP 博客系统，官方推荐的传统部署方式需要手动配置 Nginx + PHP + MySQL 环境。而通过 Docker 化部署，可以将整个运行环境打包成容器，实现一键拉起、环境隔离、快速迁移。本文记录完整的 Docker 化部署过程，从目录规划到容器编排，再到反向代理配置。

环境要求

• 操作系统：Linux（本文基于 Debian / Ubuntu 发行版）
• Docker：20.10+
• Docker Compose：2.x
• 域名：已解析到服务器 IP
• 可选：Nginx（宿主机反代）或直接使用容器内 Web 服务

前置条件

• 已安装 Docker 和 Docker Compose
• 已注册域名并完成 DNS 解析
• 建议提前准备好 MySQL 或 MariaDB 数据库信息

安装步骤

第一步：创建项目目录

mkdir -p /opt/typecho-docker/{data,backup}
cd /opt/typecho-docker

目录说明：

• data/ — 持久化存储数据库文件和 Typecho 上传资源
• backup/ — 备份目录

第二步：编写 Docker Compose 配置

创建 docker-compose.yml：

version: "3.8"

services:
  db:
    image: mariadb:10.11
    container_name: typecho-db
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: <your-db-password>
      MYSQL_DATABASE: typecho
      MYSQL_USER: typecho
      MYSQL_PASSWORD: <your-db-password>
    volumes:
      - ./data/mysql:/var/lib/mysql
    ports:
      - "127.0.0.1:3306:3306"
    networks:
      - typecho-net

  app:
    image: joyqi/typecho:latest
    container_name: typecho-app
    restart: always
    ports:
      - "127.0.0.1:9000:9000"
    volumes:
      - ./data/uploads:/app/usr/uploads
    depends_on:
      - db
    networks:
      - typecho-net

networks:
  typecho-net:
    driver: bridge

说明：数据库端口只监听 127.0.0.1，不对外暴露。app 服务使用 joyqi/typecho 官方镜像，内部运行 PHP-FPM + Nginx，监听 9000 端口。

数据库密码部分请替换为自己的强密码，建议使用 openssl rand -base64 16 生成。

第三步：启动容器

docker compose up -d

首次启动会自动拉取 MariaDB 和 Typecho 镜像，并自动创建数据库。可以使用以下命令检查状态：

docker compose ps
docker compose logs -f

第四步：配置 Nginx 反向代理

Typecho 容器监听在 127.0.0.1:9000，需要配置 Nginx 反向代理才能通过域名访问。

创建 Nginx 配置文件 /etc/nginx/sites-available/typecho.conf：

server {
    listen 80;
    server_name your-domain.com;

    # HTTP 自动跳转 HTTPS（建议配合 certbot 使用）
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate     /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    # Typecho 后端
    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # 限制上传大小（Typecho 默认 2MB，可按需调整）
    client_max_body_size 20m;
}

启用配置并重新加载 Nginx：

sudo ln -sf /etc/nginx/sites-available/typecho.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

第五步：SSL 证书（可选但推荐）

使用 certbot 申请免费 SSL 证书：

sudo certbot --nginx -d your-domain.com

certbot 会自动修改 Nginx 配置并开启 HTTPS。

第六步：通过浏览器完成安装向导

1. 访问 https://your-domain.com，进入 Typecho 安装向导
2. 填写数据库配置：

关键点：数据库地址不能填 127.0.0.1 或 localhost，因为 Typecho 运行在容器内，需要通过 Docker 网络连接到 typecho-db 这个服务名。

3. 设置管理员账号密码，完成安装

配置说明

核心配置项解析

上传目录持久化

./data/uploads:/app/usr/uploads 这个卷映射确保你在后台上传的图片、附件不会随容器销毁而丢失。

验证

通过以下方式确认部署成功：

1. 浏览器访问 https://your-domain.com，能看到 Typecho 前台界面
2. 访问 https://your-domain.com/admin/，能正常登录后台
3. 检查 Docker 容器状态：docker compose ps 显示两个容器均为 Up 状态
4. 验证上传功能：后台写一篇测试文章，上传一张图片

日常维护

备份

# 备份数据库
docker compose exec db mariadb-dump -utypecho -p<your-password> typecho > backup/typecho-$(date +%Y%m%d).sql

# 备份上传文件
cp -r data/uploads backup/uploads-$(date +%Y%m%d)

更新 Typecho

docker compose pull app
docker compose up -d --no-deps app

容器日志查看

docker compose logs -f --tail 100

常见问题

• 安装向导页面 404：检查 Nginx proxy_pass 地址和端口是否与容器映射一致。确认容器已正常运行：docker compose ps
• 数据库连接失败：Typecho 安装时数据库地址应填 typecho-db（容器服务名），不是 127.0.0.1。如果数据库在其他机器，使用该机器的 IP 地址
• 上传文件失败：检查 client_max_body_size 是否足够大。检查 uploads 目录权限：docker compose exec app chmod -R 755 /app/usr/uploads
• SSL 证书到期：certbot 会自动续期，确认 cron 任务正常：sudo certbot renew --dry-run
• 502 Bad Gateway：Typecho 容器未正常启动。查看日志定位问题：docker compose logs app

总结

Docker 化部署 Typecho 的核心优势在于环境封装和快速恢复。整个部署流程可以概括为三个步骤：编写 Compose 文件、拉起容器、配置反向代理。迁移时只需备份 data/ 目录的数据库和上传文件，新服务器上同样一套 Compose 配置即可恢复。

相比传统 LNMP 手动搭建，Docker 方式减少了环境依赖问题的排查成本，也更容易实现版本管理和回滚。

参考

• Typecho 官方文档
• Docker Compose 官方文档
• joyqi/typecho Docker 镜像