Umami云模式配置指南：如何正确启用CLOUD_MODE

Umami作为一款开源的网站分析工具，提供了云模式(CLOUD_MODE)功能，该功能可以禁用网站、用户和团队管理界面，适用于SaaS或托管场景。本文将详细介绍如何正确配置Umami的云模式。

云模式的工作原理

Umami的云模式通过两个环境变量控制：

1. CLOUD_MODE：设置为"1"或"true"时启用云模式
2. CLOUD_URL：指定用户被重定向的目标URL

当云模式启用时，Umami会：

• 隐藏网站管理界面
• 禁用用户管理功能
• 关闭团队管理选项
• 将未授权访问重定向到CLOUD_URL

配置要点

1. 环境变量设置

在Docker部署场景下，必须在构建阶段设置这两个环境变量。这是因为Umami基于Next.js框架，Next.js会在构建时将环境变量编译进应用包中。

正确的docker-compose配置示例：

services:
  umami:
    build:
      context: .
      args:
        - CLOUD_MODE=1
        - CLOUD_URL=https://your-saas-portal.com
    environment:
      - DATABASE_URL=postgres://user:pass@postgres:5432/umami

2. 变量格式说明

CLOUD_MODE接受以下值：

• "1"或"true"：启用云模式
• "0"或空值：禁用云模式

CLOUD_URL必须是完整的URL格式，例如：

• https://your-portal.com/dashboard
• http://localhost:3000/auth

3. 常见错误排查

如果云模式未生效，请检查：

1. 是否在构建阶段设置了变量（而非仅运行时环境）
2. 是否同时设置了CLOUD_MODE和CLOUD_URL
3. 变量名称是否拼写正确（全大写）
4. 是否清除了浏览器缓存（Next.js应用会缓存部分配置）

应用场景建议

云模式特别适合以下场景：

• 提供Umami托管服务的SaaS平台
• 企业内部统一监控解决方案
• 需要限制终端用户管理权限的部署环境

通过正确配置云模式，您可以实现更安全的Umami部署方案，同时保持核心数据分析功能的完整性。