在子目录安装运行 Portainer

通过宿主机 Nginx，把 Portainer CE 挂在站点的 /portainer/ 下，例如 https://your-domain.com/portainer/。

Portainer 默认认为自己在域名根路径。子目录要同时满足两件事：

• 容器启动参数带 --base-url /portainer，前端资源才会加上这个前缀。
• Nginx 把 /portainer/ 剥掉后再转发给容器。官方要求反代去掉这段路径，Portainer 内部仍以 / 提供服务。

容器定义在仓库根目录的 docker-compose.yml，宿主机 Nginx 示例在 documents/host-nginx.conf。

容器

services:
  portainer:
    container_name: portainer
    image: portainer/portainer-ce:lts
    command: --base-url /portainer --trusted-origins https://your-domain.com,https://your-domain2.com.com
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    ports:
      - 9000:9000
      - 9443:9443

volumes:
  portainer_data:
    name: portainer_data

• --base-url 不要带末尾斜杠。
• --trusted-origins 用来通过反向代理后的 CSRF 校验。每个值必须是带协议的完整 URL，多个用逗号隔开，末尾不要斜杠。不支持 * 或 https://*.aimatech.com。只从哪个域名打开，就只写哪个域名。
• 9000 是给宿主机 Nginx 用的 HTTP 端口。9443 是 Portainer 自带的 HTTPS，证书是自签名的，不要让 Nginx 去反代它。
• 如果 9000 只给本机 Nginx 用，把端口改成 127.0.0.1:9000:9000，避免 HTTP 直接暴露到公网。

启动或改完参数后重建：

docker compose up -d portainer

宿主机 Nginx

写在监听 443 的 server 里，并且放在 location / 前面。proxy_pass 末尾的 / 会去掉 /portainer/。

location = /portainer {
    return 301 /portainer/;
}

location /portainer/api/websocket/ {
    proxy_pass http://127.0.0.1:9000/api/websocket/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    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;
    proxy_read_timeout 3600s;
}

location /portainer/ {
    proxy_pass http://127.0.0.1:9000/;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    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;
    proxy_read_timeout 3600s;
}

# Portainer 的 i18n 请求写死为 /locales/，不会带上 --base-url
location /locales/ {
    proxy_pass http://127.0.0.1:9000/locales/;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    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;
}

单独的 websocket location 给容器控制台用。普通 location 里的 Connection "" 会打断升级，所以不能和它合成一段。

/locales/ 是 Portainer 的已知问题：语言包请求发到站点根路径，主站会返回 404。这段配置把它们转回 Portainer。Portainer 只自带英文包，浏览器探测 en-GB、en-GB-oxendict 时仍会 404，随后回落到 en，可以忽略。

检查并加载：

nginx -t && systemctl reload nginx

首次创建管理员

Portainer 2.39.4 / 2.43 起，新实例在创建第一个管理员时要求一次性 setup token，防止实例被别人抢先初始化。

docker logs portainer 2>&1 | grep setup_token

打开 https://<域名>/portainer/，把 setup_token= 后面的值填进 Setup token。密码至少 12 位。

限制：

• token 每次重启都会变，要用最近一次启动日志里的值。
• 必须在该次启动后的 5 分钟内完成。超时后访问会 307 到 /timeout.html，这个 Location 不带 /portainer 前缀，浏览器会跳到主站。重启容器后重新取 token，并直接打开 /portainer/。

管理员创建完成后，这个 token 不再使用。

内网且不方便从日志取 token 时，可以在首次启动时关掉校验：

command: --base-url /portainer --no-setup-token --trusted-origins https://your-domain.com

只在你完全信任的网络上使用。管理员建好后，这个参数不再起作用。

检查

curl -I http://127.0.0.1:9000/
curl -I https://your-domain.com/portainer/

本机 9000 应返回 200 或 307。经 Nginx 的地址应进入 Portainer，而不是主站。

故障

现象	原因	处理
Nginx 502	127.0.0.1:9000 没有进程	docker ps 与 docker logs portainer。改过端口或 command 后要 docker compose up -d portainer。error log 里常见 connect() failed (111: Connection refused)
启动日志 invalid url for trusted origin	--trusted-origins 格式和当前镜像不一致	2.41 及以后必须写 https://域名。更早的版本只接受纯主机名。以容器日志为准
登录或操作 Origin invalid	反代后的 Origin 不在信任列表	把浏览器地址栏里的 https://域名 加进 --trusted-origins
创建用户 403，提示缺少 X-Setup-Token	首次初始化未带 setup token	从日志复制 token，5 分钟内提交
307，Location: /timeout.html	5 分钟初始化窗口已过	docker restart portainer，重新取 token
控制台 /locales/.../translation.json 404	语言包请求没走 /portainer	加上文中的 location /locales/。en 应为 200，地区变体 404 可忽略