ehlxr/docker_practice
1
0
Fork 0
mirror of https://github.com/yeasy/docker_practice.git synced 2026-03-10 20:04:36 +00:00
Code Issues Projects Releases Wiki Activity

Add more content

Browse Source
This commit is contained in:
Baohua Yang
2026-01-30 16:48:39 -08:00
parent c58f61dbed
commit fec2e506d9
39 changed files with 8202 additions and 1063 deletions
Download Patch File Download Diff File Expand all files Collapse all files

335
compose/django.md
View File

@@ -2,41 +2,114 @@
> 本小节内容适合 `Python` 开发人员阅读。
我们现在将使用 `Docker Compose` 配置并运行一个 `Django/PostgreSQL` 应用。
本节将使用 Docker Compose 配置并运行一个 **Django + PostgreSQL** 应用。笔者不仅会介绍具体步骤，还会解释每个配置项的作用，以及开发环境和生产环境的差异。
在一切工作开始前，需要先编辑好三个必要的文件。
## 架构概览
第一步，因为应用将要运行在一个满足所有环境依赖的 Docker 容器里面，那么我们可以通过编辑 `Dockerfile` 文件来指定 Docker 容器要安装内容。内容如下：
在开始之前，让我们先理解我们要构建的架构：
```
┌─────────────────────────────────────────────────────────────┐
│ Docker Compose 网络 │
│ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ web 服务 │ │ db 服务 │ │
│ │ ┌───────────────┐ │ │ ┌───────────────┐ │ │
│ │ │ Django │ │──────│ │ PostgreSQL │ │ │
│ │ │ 应用 │ │ :5432│ │ 数据库 │ │ │
│ │ └───────────────┘ │ │ └───────────────┘ │ │
│ │ :8000 │ │ │ │
│ └──────────┬──────────┘ └─────────────────────┘ │
│ │ │
└─────────────┼───────────────────────────────────────────────┘
│
▼
localhost:8000
（浏览器访问）
```
**关键点**：
- `web` 服务运行 Django 应用，对外暴露 8000 端口
- `db` 服务运行 PostgreSQL 数据库，只在内部网络可访问
- 两个服务通过 Docker Compose 自动创建的网络相互通信
- `web` 服务可以通过服务名 `db` 访问数据库（Docker 内置 DNS）
## 准备工作
创建一个项目目录并进入：
```bash
$ mkdir django-docker && cd django-docker
```
我们需要创建三个文件：`Dockerfile`、`requirements.txt` 和 `docker-compose.yml`。
## Step 1: 创建 Dockerfile
```docker
FROM python:3
ENV PYTHONUNBUFFERED 1
RUN mkdir /code
FROM python:3.12-slim
# 防止 Python 缓冲 stdout/stderr，让日志实时输出
ENV PYTHONUNBUFFERED=1
# 设置工作目录
WORKDIR /code
# 先复制依赖文件，利用 Docker 缓存加速构建
COPY requirements.txt /code/
RUN pip install -r requirements.txt
# 安装依赖
RUN pip install --no-cache-dir -r requirements.txt
# 复制项目代码
COPY . /code/
```
以上内容指定应用将使用安装了 Python 以及必要依赖包的镜像。更多关于如何编写 `Dockerfile` 文件的信息可以查看 [ Dockerfile 使用](../image/dockerfile/README.md)。
**逐行解释**：
第二步，在 `requirements.txt` 文件里面写明需要安装的具体依赖包名。
| 指令 | 作用 | 为什么这样写 |
|------|------|-------------|
| `FROM python:3.12-slim` | 基础镜像 | `slim` 版本比完整版小很多，但包含运行 Python 所需的一切 |
| `ENV PYTHONUNBUFFERED=1` | 关闭输出缓冲 | 让 `print()` 和日志立即显示，便于调试 |
| `WORKDIR /code` | 设置工作目录 | 后续命令都在此目录执行 |
| `COPY requirements.txt` 在前 | 分层复制 | 只有 requirements.txt 变化时才重新安装依赖，加速构建 |
| `--no-cache-dir` | 不缓存 pip 下载 | 减小镜像体积 |
```bash
Django>=4.0,<5.0
psycopg2-binary>=2.9,<3.0
> 💡 **笔者建议**：总是将变化频率低的文件先复制，变化频率高的后复制。这样可以最大化利用 Docker 的构建缓存。
## Step 2: 创建 requirements.txt
```txt
Django>=5.0,<6.0
psycopg[binary]>=3.1,<4.0
gunicorn>=21.0,<22.0
```
第三步，`docker-compose.yml` 文件将把所有的东西关联起来。它描述了应用的构成（一个 web 服务和一个数据库）、使用的 Docker 镜像、镜像之间的连接、挂载到容器的卷，以及服务开放的端口。
**依赖说明**：
| 包名 | 作用 |
|------|------|
| `Django` | Web 框架 |
| `psycopg[binary]` | PostgreSQL 数据库驱动（推荐使用 psycopg 3） |
| `gunicorn` | 生产环境 WSGI 服务器（可选，开发时可不用） |
## Step 3: 创建 docker-compose.yml
```yaml
services:
db:
image: postgres
image: postgres:16
environment:
POSTGRES_PASSWORD: 'postgres'
POSTGRES_DB: django_db
POSTGRES_USER: django_user
POSTGRES_PASSWORD: django_password
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U django_user -d django_db"]
interval: 5s
timeout: 5s
retries: 5
web:
build: .
@@ -45,76 +118,222 @@ services:
- .:/code
ports:
- "8000:8000"
depends_on:
db:
condition: service_healthy
environment:
DATABASE_URL: postgres://django_user:django_password@db:5432/django_db
volumes:
postgres_data:
```
查看 [`docker-compose.yml` 章节](compose_file.md) 了解更多详细的工作机制。
**配置详解**：
现在我们就可以使用 `docker compose run` 命令启动一个 `Django` 应用了。
### db 服务
```yaml
db:
image: postgres:16 # 使用官方 PostgreSQL 16 镜像
environment:
POSTGRES_DB: django_db # 创建的数据库名
POSTGRES_USER: django_user # 数据库用户
POSTGRES_PASSWORD: django_password # 数据库密码
volumes:
- postgres_data:/var/lib/postgresql/data # 持久化数据
healthcheck: # 健康检查，确保数据库就绪
test: ["CMD-SHELL", "pg_isready -U django_user -d django_db"]
interval: 5s
```
> ⚠️ **笔者提醒**：`volumes` 配置很重要！没有它，每次容器重启数据都会丢失。笔者见过不少新手因为忘记这一步，导致开发数据全部丢失。
### web 服务
```yaml
web:
build: . # 从当前目录的 Dockerfile 构建
command: python manage.py runserver # 启动 Django 开发服务器
volumes:
- .:/code # 挂载代码目录，支持热更新
ports:
- "8000:8000" # 映射端口
depends_on:
db:
condition: service_healthy # 等待数据库健康后再启动
```
**关键配置说明**：
| 配置项 | 作用 | 笔者建议 |
|--------|------|---------|
| `volumes: .:/code` | 代码挂载 | 开发时必备，修改代码无需重新构建镜像 |
| `depends_on` + `healthcheck` | 启动顺序 | 确保数据库就绪后 Django 才启动，避免连接错误 |
| `environment` | 环境变量 | 推荐用环境变量管理配置，避免硬编码 |
## Step 4: 创建 Django 项目
运行以下命令创建新的 Django 项目：
```bash
$ docker compose run web django-admin startproject django_example .
$ docker compose run --rm web django-admin startproject mysite .
```
由于 web 服务所使用的镜像并不存在，所以 Compose 会首先使用 `Dockerfile` 为 web 服务构建一个镜像，接着使用这个镜像在容器里运行 `django-admin startproject django_example` 指令。
**命令解释**：
- `docker compose run`：运行一次性命令
- `--rm`：命令执行后删除临时容器
- `web`：在 web 服务环境中执行
- `django-admin startproject mysite .`：在当前目录创建 Django 项目
这将在当前目录生成一个 `Django` 应用。
生成的目录结构：
```bash
$ ls
Dockerfile docker-compose.yml django_example manage.py requirements.txt
```
django-docker/
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
├── manage.py
└── mysite/
├── __init__.py
├── settings.py
├── urls.py
├── asgi.py
└── wsgi.py
```
如果你的系统是 Linux,记得更改文件权限。
> 💡 **Linux 用户注意**：如果遇到权限问题，执行 `sudo chown -R $USER:$USER .`
```bash
$ sudo chown -R $USER:$USER .
```
## Step 5: 配置数据库连接
首先，我们要为应用设置好数据库的连接信息。用以下内容替换 `django_example/settings.py` 文件中 `DATABASES = ...` 定义的节点内容。
修改 `mysite/settings.py`，配置数据库连接：
```python
import os
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql',
'NAME': 'postgres',
'USER': 'postgres',
'HOST': 'db',
'NAME': os.environ.get('POSTGRES_DB', 'django_db'),
'USER': os.environ.get('POSTGRES_USER', 'django_user'),
'PASSWORD': os.environ.get('POSTGRES_PASSWORD', 'django_password'),
'HOST': 'db', # Docker Compose 服务名
'PORT': 5432,
'PASSWORD': 'postgres',
}
}
# 允许的主机（开发环境）
ALLOWED_HOSTS = ['*']
```
这些信息是在 [postgres](https://hub.docker.com/_/postgres/) 镜像固定设置好的。然后，运行 `docker compose up` ：
**为什么 HOST 是 `db` 而不是 `localhost`？**
在 Docker Compose 中，各服务通过服务名相互访问。Docker 内置的 DNS 会将 `db` 解析为 db 服务容器的 IP 地址。这是 Docker Compose 的核心功能之一。
## Step 6: 启动应用
```bash
$ docker compose up
django_db_1 is up-to-date
Creating django_web_1 ...
Creating django_web_1 ... done
Attaching to django_db_1, django_web_1
db_1 | The files belonging to this database system will be owned by user "postgres".
db_1 | This user must also own the server process.
db_1 |
db_1 | The database cluster will be initialized with locale "en_US.utf8".
db_1 | The default database encoding has accordingly been set to "UTF8".
db_1 | The default text search configuration will be set to "english".
web_1 | Performing system checks...
web_1 |
web_1 | System check identified no issues (0 silenced).
web_1 |
web_1 | November 23, 2024 - 06:21:19
web_1 | Django version 4.2, using settings 'django_example.settings'
web_1 | Starting development server at http://0.0.0.0:8000/
web_1 | Quit the server with CONTROL-C.
```
这个 `Django` 应用已经开始在你的 Docker 守护进程里监听着 `8000` 端口了。打开 `127.0.0.1:8000` 即可看到 `Django` 欢迎页面。
你会看到：
1. 首先构建 web 镜像（第一次运行）
2. 启动 db 服务，等待健康检查通过
3. 启动 web 服务
你还可以在 Docker 上运行其它的管理命令，例如对于同步数据库结构这种事，在运行完 `docker compose up` 后，在另外一个终端进入文件夹运行以下命令即可：
```
db-1 | PostgreSQL init process complete; ready for start up.
db-1 | LOG: database system is ready to accept connections
web-1 | Watching for file changes with StatReloader
web-1 | Starting development server at http://0.0.0.0:8000/
```
打开浏览器访问 http://localhost:8000，可以看到 Django 欢迎页面！
## 常用开发命令
在另一个终端窗口执行：
```bash
$ docker compose run web python manage.py migrate
# 执行数据库迁移
$ docker compose exec web python manage.py migrate
# 创建超级用户
$ docker compose exec web python manage.py createsuperuser
# 进入 Django shell
$ docker compose exec web python manage.py shell
# 进入 PostgreSQL 命令行
$ docker compose exec db psql -U django_user -d django_db
```
> 💡 笔者建议使用 `exec` 而不是 `run`。`exec` 在已运行的容器中执行命令，`run` 会创建新容器。
## 常见问题排查
### Q1: 数据库连接失败
**错误信息**：`django.db.utils.OperationalError: could not connect to server`
**可能原因与解决方案**：
| 原因 | 解决方案 |
|------|---------|
| 数据库还没启动完成 | 使用 `depends_on` + `healthcheck` |
| HOST 配置错误 | 确保使用服务名 `db` 而不是 `localhost` |
| 网络未创建 | 运行 `docker compose down` 后重新 `up` |
```bash
# 调试：检查数据库是否正常运行
$ docker compose ps
$ docker compose logs db
```
### Q2: 代码修改没有生效
**可能原因**：
1. **开发服务器没有自动重载**：确保使用 `runserver` 而不是 `gunicorn`
2. **Volume 挂载问题**：检查 `docker-compose.yml` 中的 volumes 配置
3. **缓存问题**：尝试 `docker compose restart web`
### Q3: 权限问题（Linux）
```bash
# 如果容器内创建的文件 root 用户所有
$ sudo chown -R $USER:$USER .
```
## 开发 vs 生产：关键差异
笔者特别提醒，本节的配置是**开发环境**配置。生产环境需要以下调整：
| 配置项 | 开发环境 | 生产环境 |
|--------|---------|---------|
| **Web 服务器** | `runserver` | `gunicorn` + Nginx |
| **DEBUG** | `True` | `False` |
| **密码管理** | 明文写在配置 | 使用 Docker Secrets 或环境变量 |
| **Volume** | 挂载代码目录 | 代码直接 COPY 进镜像 |
| **ALLOWED_HOSTS** | `['*']` | 具体域名 |
**生产环境 docker-compose.yml 示例**：
```yaml
# docker-compose.prod.yml
services:
web:
build: .
command: gunicorn mysite.wsgi:application --bind 0.0.0.0:8000
# 不挂载代码，使用镜像内的代码
environment:
DEBUG: 'False'
ALLOWED_HOSTS: 'example.com,www.example.com'
# ...
```
## 延伸阅读
- [Compose 模板文件详解](compose_file.md)：深入理解 docker-compose.yml 的所有配置项
- [使用 WordPress](wordpress.md)：另一个 Compose 实战案例
- [Dockerfile 最佳实践](../appendix/best_practices.md)：构建更小、更安全的镜像
- [数据管理](../data_management/README.md)：Volume 和数据持久化详解

261
compose/rails.md
View File

@@ -1,117 +1,268 @@
# 使用 Rails
> 本小节内容适合 `Ruby` 开发人员阅读。
> 本小节内容适合 Ruby 开发人员阅读。
我们现在将使用 `Compose` 配置并运行一个 `Rails/PostgreSQL` 应用。
本节使用 Docker Compose 配置并运行一个 **Rails + PostgreSQL** 应用。
在一切工作开始前，需要先设置好三个必要的文件。
## 架构概览
首先，因为应用将要运行在一个满足所有环境依赖的 Docker 容器里面，那么我们可以通过编辑 `Dockerfile` 文件来指定 Docker 容器要安装内容。内容如下：
```docker
FROM ruby
RUN apt-get update -qq && apt-get install -y build-essential libpq-dev
RUN mkdir /myapp
WORKDIR /myapp
ADD Gemfile /myapp/Gemfile
RUN bundle install
ADD . /myapp
```
┌─────────────────────────────────────────────────────────────┐
│ Docker Compose 网络 │
│ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ web 服务 │ │ db 服务 │ │
│ │ ┌───────────────┐ │ │ ┌───────────────┐ │ │
│ │ │ Rails │ │──────│ │ PostgreSQL │ │ │
│ │ │ 应用 │ │ :5432│ │ 数据库 │ │ │
│ │ └───────────────┘ │ │ └───────────────┘ │ │
│ │ :3000 │ │ │ │
│ └──────────┬──────────┘ └─────────────────────┘ │
│ │ │
└─────────────┼───────────────────────────────────────────────┘
│
▼
localhost:3000
```
以上内容指定应用将使用安装了 Ruby、Bundler 以及其依赖件的镜像。更多关于如何编写 Dockerfile 文件的信息可以查看 [Dockerfile 使用](../image/dockerfile/README.md)。
## 准备工作
下一步，我们需要一个引导加载 Rails 的文件 `Gemfile` 。 等一会儿它还会被 `rails new` 命令覆盖重写。
创建项目目录：
```bash
source 'https://rubygems.org'
gem 'rails', '4.0.2'
$ mkdir rails-docker && cd rails-docker
```
最后，`docker-compose.yml` 文件才是最神奇的地方。 `docker-compose.yml` 文件将把所有的东西关联起来。它描述了应用的构成（一个 web 服务和一个数据库）、每个镜像的来源（数据库运行在使用预定义的 PostgreSQL 镜像，web 应用侧将从本地目录创建）、镜像之间的连接，以及服务开放的端口。
需要创建三个文件：`Dockerfile`、`Gemfile` 和 `docker-compose.yml`。
## Step 1: 创建 Dockerfile
```docker
FROM ruby:3.2
# 安装系统依赖
RUN apt-get update -qq && \
apt-get install -y build-essential libpq-dev nodejs && \
rm -rf /var/lib/apt/lists/*
# 设置工作目录
WORKDIR /myapp
# 先复制 Gemfile，利用缓存加速构建
COPY Gemfile /myapp/Gemfile
COPY Gemfile.lock /myapp/Gemfile.lock
RUN bundle install
# 复制应用代码
COPY . /myapp
```
**配置说明**：
| 指令 | 作用 |
|------|------|
| `build-essential` | 编译原生扩展所需 |
| `libpq-dev` | PostgreSQL 客户端库 |
| `nodejs` | Rails Asset Pipeline 需要 |
| 先复制 Gemfile | 只有依赖变化时才重新 `bundle install` |
## Step 2: 创建 Gemfile
创建一个初始的 `Gemfile`，稍后会被 `rails new` 覆盖：
```ruby
source 'https://rubygems.org'
gem 'rails', '~> 7.1'
```
创建空的 `Gemfile.lock`：
```bash
$ touch Gemfile.lock
```
## Step 3: 创建 docker-compose.yml
```yaml
services:
db:
image: postgres
ports:
- "5432"
image: postgres:16
environment:
POSTGRES_PASSWORD: password
volumes:
- postgres_data:/var/lib/postgresql/data
web:
build: .
command: bundle exec rackup -p 3000
command: bash -c "rm -f tmp/pids/server.pid && bundle exec rails s -p 3000 -b '0.0.0.0'"
volumes:
- .:/myapp
ports:
- "3000:3000"
depends_on:
- db
environment:
DATABASE_URL: postgres://postgres:password@db:5432/myapp_development
volumes:
postgres_data:
```
所有文件就绪后，我们就可以通过使用 `docker compose run` 命令生成应用的骨架了。
**配置详解**：
| 配置项 | 说明 |
|--------|------|
| `rm -f tmp/pids/server.pid` | 清理上次异常退出留下的 PID 文件 |
| `volumes: .:/myapp` | 挂载代码目录，支持热更新 |
| `depends_on: db` | 确保数据库先启动 |
| `DATABASE_URL` | Rails 12-factor 风格的数据库配置 |
## Step 4: 生成 Rails 项目
使用 `docker compose run` 生成项目骨架：
```bash
$ docker compose run web rails new . --force --database=postgresql --skip-bundle
$ docker compose run --rm web rails new . --force --database=postgresql --skip-bundle
```
`Compose` 会先使用 `Dockerfile` 为 web 服务创建一个镜像，接着使用这个镜像在容器里运行 `rails new ` 和它之后的命令。一旦这个命令运行完后，应该就可以看一个崭新的应用已经生成了。
**命令解释**：
- `--rm`：执行后删除临时容器
- `--force`：覆盖已存在的文件
- `--database=postgresql`：配置使用 PostgreSQL
- `--skip-bundle`：暂不安装依赖（稍后统一安装）
生成的目录结构：
```bash
$ ls
Dockerfile app docker-compose.yml tmp
Gemfile bin lib vendor
Gemfile.lock condocker-compose log
README.rdoc condocker-compose.ru public
Rakefile db test
Dockerfile Gemfile Rakefile config lib tmp
Gemfile.lock README.md app config.ru log vendor
docker-compose.yml bin db public
```
在新的 `Gemfile` 文件去掉加载 `therubyracer` 的行的注释，这样我们便可以使用 Javascript 运行环境：
> ⚠️ **Linux 用户**：如遇权限问题，执行 `sudo chown -R $USER:$USER .`
```bash
gem 'therubyracer', platforms: :ruby
```
## Step 5: 重新构建镜像
现在我们已经有一个新的 `Gemfile` 文件，需要再重新创建镜像。（这个会步骤会改变 Dockerfile 文件本身，所以需要重建一次）。
由于生成了新的 Gemfile，需要重新构建镜像以安装完整依赖：
```bash
$ docker compose build
```
应用现在就可以启动了，但配置还未完成。Rails 默认读取的数据库目标是 `localhost` ，我们需要手动指定容器的 `db` 。同样的，还需要把用户名修改成和 postgres 镜像预定的一致。
打开最新生成的 `database.yml` 文件。用以下内容替换：
## Step 6: 配置数据库连接
```bash
development: &default
修改 `config/database.yml`：
```yaml
default: &default
adapter: postgresql
encoding: unicode
database: postgres
pool: 5
username: postgres
password:
host: db
pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
url: <%= ENV['DATABASE_URL'] %>
development:
<<: *default
test:
<<: *default
database: myapp_test
production:
<<: *default
```
现在就可以启动应用了。
> 💡 使用 `DATABASE_URL` 环境变量配置数据库，符合 12-factor 应用原则，便于在不同环境间切换。
## Step 7: 启动应用
```bash
$ docker compose up
```
如果一切正常，你应该可以看到 PostgreSQL 的输出，几秒后可以看到这样的重复信息：
输出示例：
```bash
myapp_web_1 | [2014-01-17 17:16:29] INFO WEBrick 1.3.1
myapp_web_1 | [2014-01-17 17:16:29] INFO ruby 2.0.0 (2013-11-22) [x86_64-linux-gnu]
myapp_web_1 | [2014-01-17 17:16:29] INFO WEBrick::HTTPServer#start: pid=1 port=3000
```
db-1 | PostgreSQL init process complete; ready for start up.
db-1 | LOG: database system is ready to accept connections
web-1 | => Booting Puma
web-1 | => Rails 7.1.0 application starting in development
web-1 | => Run `bin/rails server --help` for more startup options
web-1 | Puma starting in single mode...
web-1 | * Listening on http://0.0.0.0:3000
```
最后， 我们需要做的是创建数据库，打开另一个终端，运行：
## Step 8: 创建数据库
在另一个终端执行：
```bash
$ docker compose run web rake db:create
$ docker compose exec web rails db:create
Created database 'myapp_development'
Created database 'myapp_test'
```
这个 web 应用已经开始在你的 docker 守护进程里面监听着 3000 端口了。
访问 http://localhost:3000 查看 Rails 欢迎页面。
## 常用开发命令
```bash
# 数据库迁移
$ docker compose exec web rails db:migrate
# Rails 控制台
$ docker compose exec web rails console
# 运行测试
$ docker compose exec web rails test
# 生成脚手架
$ docker compose exec web rails generate scaffold Post title:string body:text
# 进入容器 Shell
$ docker compose exec web bash
```
## 常见问题
### Q: 数据库连接失败
检查 `DATABASE_URL` 环境变量格式是否正确，确保 db 服务已启动：
```bash
$ docker compose ps
$ docker compose logs db
```
### Q: server.pid 文件导致启动失败
错误信息：`A server is already running`
已在 command 中添加 `rm -f tmp/pids/server.pid` 处理。如仍有问题：
```bash
$ docker compose exec web rm -f tmp/pids/server.pid
```
### Q: Gem 安装失败
可能需要更新 bundler 或清理缓存：
```bash
$ docker compose run --rm web bundle update
```
## 开发 vs 生产
| 配置项 | 开发环境 | 生产环境 |
|--------|---------|---------|
| Rails 服务器 | Puma (开发模式) | Puma + Nginx |
| 代码挂载 | 使用 volumes | 代码打包进镜像 |
| 静态资源 | 动态编译 | 预编译 (`rails assets:precompile`) |
| 数据库密码 | 明文配置 | 使用 Secrets 管理 |
## 延伸阅读
- [使用 Django](django.md)：Python Web 框架实战
- [Compose 模板文件](compose_file.md)：配置详解
- [数据管理](../data_management/README.md)：数据持久化

245
compose/wordpress.md
View File

@@ -1,51 +1,210 @@
# 使用 WordPress
# 实战 WordPress
> 本小节内容适合 `PHP` 开发人员阅读。
## 简介
`Compose` 可以很便捷的让 `Wordpress` 运行在一个独立的环境中。
WordPress 是全球最流行的内容管理系统（CMS）。使用 Docker Compose 可以在几分钟内搭建一个包含数据库、Web 服务和持久化存储的生产级 WordPress 环境。
## 创建空文件夹
---
假设新建一个名为 `wordpress` 的文件夹，然后进入这个文件夹。
## 项目结构
## 创建 `docker-compose.yml` 文件
[`docker-compose.yml`](https://github.com/yeasy/docker_practice/blob/master/compose/demo/wordpress/docker-compose.yml) 文件将开启一个 `wordpress` 服务和一个独立的 `MySQL` 实例：
```yaml
services:
db:
image: mysql:8.0
command:
- --default_authentication_plugin=mysql_native_password
- --character-set-server=utf8mb4
- --collation-server=utf8mb4_unicode_ci
volumes:
- db_data:/var/lib/mysql
restart: always
environment:
MYSQL_ROOT_PASSWORD: somewordpress
MYSQL_DATABASE: wordpress
MYSQL_USER: wordpress
MYSQL_PASSWORD: wordpress
wordpress:
depends_on:
- db
image: wordpress:latest
ports:
- "8000:80"
restart: always
environment:
WORDPRESS_DB_HOST: db:3306
WORDPRESS_DB_USER: wordpress
WORDPRESS_DB_PASSWORD: wordpress
volumes:
db_data:
```
wordpress/
├── docker-compose.yml
├── .env # 环境变量（敏感信息）
└── nginx/ # 可选：反向代理配置
└── nginx.conf
```
## 构建并运行项目
---
运行 `docker compose up -d` Compose 就会拉取镜像再创建我们所需要的镜像，然后启动 `wordpress` 和数据库容器。 接着浏览器访问 `127.0.0.1:8000` 端口就能看到 `WordPress` 安装界面了。
## 编写 `docker-compose.yml`
这是一个生产可用的最小化配置：
```yaml
services:
# 数据库服务
db:
image: mysql:8.0
container_name: wordpress_db
restart: always
command:
# 使用原生密码认证（旧版 WP 兼容性）
- --default-authentication-plugin=mysql_native_password
- --character-set-server=utf8mb4
- --collation-server=utf8mb4_unicode_ci
environment:
MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
MYSQL_DATABASE: wordpress
MYSQL_USER: wordpress
MYSQL_PASSWORD: ${DB_PASSWORD}
volumes:
- db_data:/var/lib/mysql
networks:
- wp_net
# WordPress 服务
wordpress:
image: wordpress:latest
container_name: wordpress_app
restart: always
ports:
- "8000:80"
environment:
WORDPRESS_DB_HOST: db:3306
WORDPRESS_DB_USER: wordpress
WORDPRESS_DB_PASSWORD: ${DB_PASSWORD}
WORDPRESS_DB_NAME: wordpress
volumes:
- wp_data:/var/www/html
# 增加上传文件大小限制
- ./uploads.ini:/usr/local/etc/php/conf.d/uploads.ini
depends_on:
- db
networks:
- wp_net
volumes:
db_data: # 数据库持久化
wp_data: # WordPress 文件(插件/主题/上传)持久化
networks:
wp_net:
```
---
## 配置文件详解
### 1. 环境变量 (.env)
为了安全，不要在 `docker-compose.yml` 中直接写密码。创建 `.env` 文件：
```ini
DB_ROOT_PASSWORD=somestrongrootpassword
DB_PASSWORD=somestronguserpassword
```
Compose 会自动读取此同级目录下的文件。
### 2. 数据持久化
我们定义了两个命名卷：
- `db_data`: 确保 MySQL 容器重建后数据不丢失
- `wp_data`: 保存 WordPress 的核心文件、插件、主题和上传的媒体文件
### 3. PHP 配置优化
默认的 WordPress 镜像上传文件限制较小（通常 2MB）。创建 `uploads.ini`：
```ini
file_uploads = On
memory_limit = 256M
upload_max_filesize = 64M
post_max_size = 64M
max_execution_time = 600
```
---
## 启动与运行
1. 启动服务：
```bash
$ docker compose up -d
```
2. 访问安装界面：
打开浏览器访问 `http://localhost:8000`
3. 查看日志：
```bash
$ docker compose logs -f
```
---
## 生产环境最佳实践
### 1. 数据库备份
不要只依赖 Volume。建议定期备份数据库：
```bash
# 导出 SQL
$ docker exec wordpress_db mysqldump -u wordpress -pwordpress wordpress > backup.sql
```
或者添加一个自动备份容器：
```yaml
backup:
image: tiredofit/db-backup
volumes:
- ./backups:/backup
environment:
- DB_TYPE=mysql
- DB_HOST=db
- DB_NAME=wordpress
- DB_USER=wordpress
- DB_PASS=${DB_PASSWORD}
- DB_DUMP_FREQ=1440 # 每天备份一次
depends_on:
- db
networks:
- wp_net
```
### 2. 使用 Nginx 反向代理
在生产环境中，不要直接暴露 WordPress 端口，而是通过 Nginx 进行反向代理并配置 SSL。
### 3. 使用 Redis 缓存
WordPress 支持 Redis 缓存以提高性能。
```yaml
redis:
image: redis:alpine
restart: always
networks:
- wp_net
```
在 WordPress 容器环境变量中添加：
```yaml
WORDPRESS_REDIS_HOST: redis
```
并安装 Redis Object Cache 插件。
---
## 常见问题
### Q: 数据库连接错误
**现象**：访问页面显示 "Error establishing a database connection"。
**排查**：
1. 检查 `docker compose logs wordpress`
2. 确认 `.env` 中的密码与 YAML 文件引用一致
3. 确认 `WORDPRESS_DB_HOST` 也是 `db`（服务名）
4. MySQL 8.0 可能需要几秒钟启动，WordPress 会自动重试，稍等片刻即可。
### Q: 无法上传大文件
**解决**：确保挂载了 `uploads.ini` 配置，并且重启了容器：
```bash
$ docker compose restart wordpress
```
---
## 延伸阅读
- [Compose 模板文件](compose_file.md)：深入了解配置项
- [数据卷](../data_management/volume.md)：理解数据持久化
- [Docker Hub WordPress](https://hub.docker.com/_/wordpress)：官方镜像文档