base_url必须为https完整域名，secret_key_base须用openssl rand -hex 64生成，admin_user/admin_password建议显式设置；docker-compose.yml中ports、env_file等字段不可照抄，nginx反代需透传x-forwarded-proto且server_name与base_url一致。
BASE_URL 必须是 HTTPS 完整域名，SECRET_KEY_BASE 必须用 openssl rand -hex 64 生成，否则服务起不来或登录态丢失——这不是可选项，是硬性要求。
docker-compose.yml 里哪些字段不能照抄
你从 GitHub 或博客复制的 docker-compose.yml 很可能直接导致启动失败或无法登录，关键字段必须手动改：
-
BASE_URL必须写成https://stats.example.com（带协议、完整域名），不能是http://localhost:8000、IP 地址或缺协议——否则前端脚本被浏览器拦截，页面空白或报跨域错误 -
SECRET_KEY_BASE必须执行openssl rand -hex 64生成新值，不能留空、不能复用别人示例里的字符串，否则容器重启后 session 全丢，登录页反复跳回 -
ADMIN_USER和ADMIN_PASSWORD建议显式声明，不依赖默认值admin/admin；否则首次登录后系统强制改密，但没提示，容易误判为账号密码错 - 若后续配 Nginx 反代，
ports应设为- "127.0.0.1:8000:8000"，避免端口直曝公网；单机测试才用- "8000:8000"
启动后打不开页面？先查这三件事
执行 docker-compose up -d 后访问不了，别急着重装，按顺序排查：
- 运行
docker-compose ps，确认plausible和postgres都是Up状态；如果postgres显示Restarting，大概率是./postgres目录权限问题（Ubuntu 常见），执行sudo chown -R $USER:$USER ./data ./postgres修复 - 运行
docker logs plausible，重点看是否有FATAL: database files are incompatible with server（删掉./postgres重来）或waiting for postgres（说明依赖未就绪，建议在docker-compose.yml中给postgres加healthcheck并让plausible用depends_on等待） - 在服务器本地执行
curl -v http://localhost:8000/healthz，返回200 OK说明容器内服务正常；否则问题在容器外：检查ufw是否开着、云平台安全组是否放行了 8000 端口
Nginx 反向代理配 HTTPS 的关键点
暴露 8000 端口风险高，且影响前端脚本加载。Nginx 是最稳妥出口，但配置稍有偏差就会翻车：
-
BASE_URL和 Nginx 的server_name必须完全一致，比如都设为stats.example.com；否则 Plausible 后端生成的重定向 URL 会跳回 HTTP，登录后 302 到http://...被浏览器拒绝 - Nginx 配置中必须透传
X-Forwarded-Proto和X-Real-IP，否则 Plausible 无法识别真实协议和访客 IP；漏掉proxy_set_header X-Forwarded-Proto $scheme;就会出问题 - 证书要用 Certbot 自动续期，别手动生成；
certbot --nginx -d stats.example.com会自动改 Nginx 配置并加 cron 续期任务
环境变量文件名和路径容易混淆
Plausible 官方推荐用 .env 或 plausible-conf.env，但实际生效取决于 docker-compose.yml 中怎么引用：
- 如果
docker-compose.yml里写的是env_file: plausible-conf.env，那就必须叫这个名字，不能叫.env - 如果用了
environment:直接定义变量，.env文件会被忽略——别以为写了就自动加载 -
DISABLE_REGISTRATION=true建议加上，否则任何人都能注册账号；这个开关只在首次启动时生效，改完再重启不生效
真正卡住人的从来不是安装步骤，而是 BASE_URL 协议不匹配、SECRET_KEY_BASE 复用、PostgreSQL 数据目录权限这三处细节。只要它们对了，其余都是顺下来的。
