Monica Docker 镜像使用指南

快速参考

维护方

Monica 团队

获取帮助的途径

• Docker 社区 Slack：[***]
• Server Fault：[***]
• Unix & Linux：[***]
• Stack Overflow：[***]

支持的标签及对应 Dockerfile 链接

以下是 Monica 镜像的常用标签及对应的 Dockerfile 源码链接：

• 4.1.2-apache、4.1-apache、4-apache、apache、4.1.2、4.1、4、latest
  Dockerfile

• 4.1.2-fpm-alpine、4.1-fpm-alpine、4-fpm-alpine、fpm-alpine
  Dockerfile

• 4.1.2-fpm、4.1-fpm、4-fpm、fpm
  Dockerfile

• 5.0.0-beta.5-apache、5.0.0-beta-apache、5.0-apache
  Dockerfile

• 5.0.0-beta.5-fpm-alpine、5.0.0-beta-fpm-alpine、5.0-fpm-alpine
  Dockerfile

• 5.0.0-beta.5-fpm、5.0.0-beta-fpm、5.0-fpm
  Dockerfile

快速参考（续）

提交问题的地址

[***]

支持的架构

（更多信息见 官方说明）
amd64、arm32v5、arm32v6、arm32v7、arm64v8、i386、ppc64le、riscv64、s390x
（各架构镜像地址可通过链接查看，如 amd64）

镜像 artifact 详情

包括镜像元数据、传输大小等，可查看 repo-info 仓库的 repos/monica/ 目录（历史记录）

镜像更新

• 官方镜像仓库标签：library/monica label
• 官方镜像配置文件：library/monica file（历史记录）

本文档来源

docs 仓库的 monica/ 目录（历史记录）

什么是 Monica？

Monica 是一款优秀的开源个人关系管理系统，可帮助你整理与亲友的互动记录。

!logo

如何使用本镜像

Monica 镜像提供两种版本，可根据需求选择：

• apache 标签：包含完整的 Monica 安装及 Apache Web 服务器，也是默认 latest 标签指向的版本。
• fpm 标签：仅包含 FastCGI 进程（用于处理网页请求），需配合 Apache 或 Nginx 等反向代理服务器使用。

使用 apache 镜像

该镜像内置 Web 服务器，暴露 80 端口。运行容器命令如下：

docker run --name some-monica -d -p 8080:80 monica

使用 fpm 镜像

该镜像运行 FastCGI 服务器，暴露 9000 端口，需搭配反向代理服务器。运行容器命令如下：

docker run --name some-monica -d -p 9000:9000 monica:fpm

使用外部数据库

Monica 需依赖外部数据库（支持 MySQL/MariaDB）。可通过 --link 参数链接数据库容器（如 --link my-mysql:db），并在配置时将数据库主机设为 db。详细配置可参考下文 Docker Compose 部分。

持久化存储

为避免数据丢失，需为数据库和 Monica 的 /var/www/html/storage 目录挂载卷。例如，使用命名卷保存 Monica 数据：

docker run -d \
        -v monica_data:/var/www/html/storage \
        monica

在容器内执行命令

作为 Laravel 应用，php artisan 命令对 Monica 管理非常重要。在容器内执行命令的方式如下：

• 直接使用容器 ID：

  docker exec 容器ID php artisan 命令
  

• 使用 Docker Compose（假设服务名为 monica）：

  docker compose exec monica php artisan 命令
  

通过环境变量配置

Monica 镜像通过环境变量进行配置，常用变量可参考 Monica 官方文档（.env.example 文件）。

使用 Docker Compose 运行镜像

可参考 示例目录 中的 Docker Compose 配置，以下为两种常用场景的配置步骤。

Apache 版本

该配置使用 apache 镜像，并搭配 MariaDB 数据库容器，通过卷实现数据持久化。注意：此配置不含 SSL 加密，建议用于反向代理后端。

步骤：

1. 创建 compose.yaml 文件，内容如下：

   services:
     app:
       image: monica
       depends_on:
         - db
       ports:
         - 8080:80
       environment:
         - APP_KEY= # 生成方法：运行 `echo -n 'base64:'; openssl rand -base64 32`
         - DB_HOST=db
         - DB_USERNAME=monica
         - DB_PASSWORD=secret  # 建议替换为自定义密码
       volumes:
         - data:/var/www/html/storage
       restart: always
   
     db:
       image: mariadb:11
       environment:
         - MYSQL_RANDOM_ROOT_PASSWORD=true
         - MYSQL_DATABASE=monica
         - MYSQL_USER=monica
         - MYSQL_PASSWORD=secret  # 与上方 DB_PASSWORD 保持一致
       volumes:
         - mysql:/var/lib/mysql
       restart: always
   
   volumes:
     data:
       name: data
     mysql:
       name: mysql
   

2. 生成 APP_KEY：
   执行命令 echo -n 'base64:'; openssl rand -base64 32，将输出结果填入 APP_KEY 字段。

3. 启动服务：

   docker compose up -d
   

   等待数据库迁移完成后，通过 `[***] 访问 Monica，确认正常后可创建首个用户。

4. 执行初始化命令（仅需一次）：

   docker compose exec app php artisan setup:production
   

FPM 版本

FPM 镜像需搭配 Web 服务器（如 Nginx）处理 HTTP 请求。以下为 Nginx + FPM + MariaDB 的配置示例。

步骤：

1. 准备 Nginx 配置文件：
   创建 web 目录，下载示例配置：

   mkdir web
   curl -sSL [***] -o web/nginx.conf
   curl -sSL [***] -o web/Dockerfile
   

   构建 Nginx 镜像：docker compose build（每次部署前建议重新构建）。

2. 创建 compose.yaml 文件，内容如下：

   services:
     app:
       image: monica:fpm
       depends_on:
         - db
       environment:
         - APP_KEY= # 生成方法同上：`echo -n 'base64:'; openssl rand -base64 32`
         - DB_HOST=db
         - DB_USERNAME=monica
         - DB_PASSWORD=secret  # 自定义密码
       volumes:
         - data:/var/www/html/storage
       restart: always
   
     web:
       build: ./web
       ports:
         - 8080:80
       depends_on:
         - app
       volumes:
         - data:/var/www/html/storage:ro  # 只读挂载
       restart: always
   
     db:
       image: mariadb:11
       environment:
         - MYSQL_RANDOM_ROOT_PASSWORD=true
         - MYSQL_DATABASE=monica
         - MYSQL_USER=monica
         - MYSQL_PASSWORD=secret  # 与上方 DB_PASSWORD 一致
       volumes:
         - mysql:/var/lib/mysql
       restart: always
   
   volumes:
     data:
       name: data
     mysql:
       name: mysql
   

3. 生成并填入 APP_KEY（同 Apache 版本步骤 2）。

4. 启动服务：

   docker compose up -d
   

   等待数据库迁移完成后，通过 `[***] 访问 Monica。

5. 执行初始化命令（仅需一次）：

   docker compose exec app php artisan setup:production
   

将 Monica 暴露到互联网

若需通过互联网访问 Monica，需设置环境变量 APP_ENV=production，此时强制启用 HTTPS。

暴露方式

• 通过主机代理服务器：在主机部署带 SSL 功能的 Web 服务器（如 Nginx），作为反向代理。
• 通过容器化代理服务器：参考 示例目录 中的 SSL 配置示例。

镜像变体

Monica 镜像提供多种变体，适用于不同场景：

monica:<version>

默认镜像，包含完整依赖及 Apache 服务器，适合快速部署。

monica:<version>-alpine

基于 Alpine Linux 的轻量级镜像，体积更小（约 5MB 基础镜像）。特点：

• 使用 musl libc 而非 glibc，部分依赖较深的软件可能存在兼容性问题（详细讨论见 Hacker News 评论）。
• 通常不含 git、bash 等工具，需在自定义 Dockerfile 中额外安装。

许可证

• 镜像中软件的许可证信息见 Monica 仓库 LICENSE.md。
• 镜像可能包含其他软件（如基础系统工具、依赖库等），其许可证需用户自行确认合规性。
• 自动检测的许可证信息可参考 repo-info 仓库的 monica/ 目录。

使用前请确保遵守所有包含软件的许可证要求。