如何在Nginx子路径/analytics下配置Piwik:fpm Docker容器

我之前帮不少用户搞定过Piwik（现在改叫Matomo了）在子路径下部署的坑，结合你用Docker Compose + Piwik FPM + Nginx的场景，给你一套绝对可行的配置方案——得两步走，先搞定Piwik内部的路径设置，再调整Nginx的规则，最后检查Docker的挂载是否到位。

第一步：先配置Piwik的子路径访问（必须做！） #

如果跳过这一步，就算Nginx配置对了，页面也会出现CSS/JS加载失败、跳转错误的问题，这是很多人踩坑的地方。

1. 先通过原来的根路径访问并登录Piwik后台（如果还能访问的话）
2. 进入设置 > 系统 > 通用设置
3. 修改两个关键配置：
   • 网站URL：改成你的子路径地址，比如 http://localhost/analytics
   • Matomo URL：同样改成 http://localhost/analytics
4. 保存设置后，进入设置 > 系统 > 诊断，确认“Matomo URL”和“网站URL”已经更新正确
5. 最后清除Piwik的缓存：在后台右上角点击你的用户名，选择清除缓存

如果已经没法通过根路径访问了，也可以直接修改Piwik的配置文件：
找到Piwik容器里的config/config.ini.php，添加或修改[General]段的配置：

[General]
base_url = "http://localhost/analytics/"
trusted_hosts[] = "localhost"

第二步：调整Nginx的配置 #

下面是针对Piwik FPM的完整Nginx server配置，重点是正确处理静态文件和PHP请求的子路径映射，每部分我都加了注释：

server {
    listen 80;
    server_name localhost;

    # 处理/analytics子路径的请求
    location /analytics {
        # 这里的路径是Nginx容器内Piwik静态文件的存放目录
        # 对应Docker Compose中挂载的Piwik web根目录（piwik:fpm的web根是/usr/src/piwik）
        alias /usr/share/nginx/html/piwik;
        index index.php;

        # 处理静态资源（图片、CSS、JS等），直接返回并设置缓存
        location ~ ^/analytics/.+\.(png|jpg|jpeg|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {
            alias /usr/share/nginx/html/piwik;
            expires 30d;
            access_log off;
            add_header Cache-Control "public, immutable";
        }

        # 处理PHP请求，转发到Piwik FPM容器
        location ~ ^/analytics/.+\.php$ {
            alias /usr/share/nginx/html/piwik;
            # 这里的piwik是Docker Compose中Piwik服务的名称，要和你的compose文件一致
            fastcgi_pass piwik:9000;
            fastcgi_index index.php;

            # 关键：传递正确的脚本文件名给FPM
            fastcgi_param SCRIPT_FILENAME $request_filename;
            include fastcgi_params;

            # 必须设置这两个参数，让Piwik知道自己在子路径下
            fastcgi_param PATH_INFO $fastcgi_path_info;
            fastcgi_param SCRIPT_NAME /analytics$fastcgi_script_name;
        }
    }
}

第三步：确保Docker Compose的挂载正确 #

要让Nginx能访问到Piwik的静态文件，需要在Docker Compose中把Piwik的web根目录共享给Nginx容器，下面是核心部分的配置（你可以保留原来的数据库等配置）：

version: '3.8'

services:
  piwik:
    image: piwik:fpm
    volumes:
      # 存储Piwik的用户数据和配置
      - piwik_data:/var/www/html
      # 共享Piwik的web静态文件给Nginx
      - piwik_web:/usr/src/piwik
    # 保持你原来的数据库环境变量配置
    environment:
      - PIWIK_DATABASE_HOST=db
      - PIWIK_DATABASE_USER=piwik
      - PIWIK_DATABASE_PASSWORD=your_password
      - PIWIK_DATABASE_NAME=piwik
    depends_on:
      - db

  nginx:
    image: nginx:alpine
    volumes:
      # 挂载你的Nginx配置文件
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
      # 挂载Piwik的web静态文件
      - piwik_web:/usr/share/nginx/html/piwik
    ports:
      - "80:80"
    depends_on:
      - piwik

  # 保留你原来的数据库服务配置
  db:
    image: mysql:5.7
    volumes:
      - db_data:/var/lib/mysql
    environment:
      - MYSQL_ROOT_PASSWORD=your_root_password
      - MYSQL_DATABASE=piwik
      - MYSQL_USER=piwik
      - MYSQL_PASSWORD=your_password

volumes:
  piwik_data:
  piwik_web:
  db_data:

最后验证 #

1. 重启所有容器：docker-compose down && docker-compose up -d
2. 访问http://localhost/analytics，应该能正常加载Piwik界面，没有资源加载错误
3. 如果还有问题，检查Nginx的日志：docker-compose logs nginx，看看有没有404或者fastcgi错误，根据日志排查就行

内容的提问来源于stack exchange，提问作者Guillaume