mod_vhost_alias通过VirtualDocumentRoot实现子域名自动映射，需前置配置DNS泛解析、文件系统目录结构及关闭UseCanonicalName；核心指令为VirtualDocumentRoot /var/www/%1，支持%2、%-1等变量处理多级子域名。

mod_vhost_alias 本身不提供“全自动解析”，它只做运行时路径映射，真正的“自动”依赖你提前配好三件事：DNS泛解析、文件系统结构、Host头合法性控制。核心层能做的，是把 user.example.com 这类请求，在 Apache 接收后立刻映射到 /var/www/user/，跳过写几百个 <VirtualHost> 块。

---

必须前置完成的三件事

• DNS 已配置 *.example.com A 记录指向服务器 IP
• 文件系统中每个子域名对应目录已存在（如 /var/www/alice/），且 Apache 进程用户（如 www-data）有执行权限进入该目录、读取文件
• 在配置中显式关闭 UseCanonicalName，否则 %1 等变量取不到 Host 头内容

---

关键配置：用 VirtualDocumentRoot 动态绑定

在启用模块后（a2enmod vhost_alias 或确认 LoadModule vhost_alias_module 已加载），添加如下 <VirtualHost>：

Apache Superset Dashboard and SQL Exploration Skill

Apache Superset 是一个广泛采用的开源 BI 平台，用于 SQL 探索、图表构建和仪表板交付。当代理需要查询仓库数据、组装仪表板或使用成熟的分析界面解释指标而不是临时笔记本代码时，此技能非常有用。

下载

<VirtualHost *:80>
    ServerName example.com
    ServerAlias *.example.com
    UseCanonicalName Off
    VirtualDocumentRoot /var/www/%1
    VirtualScriptAlias /var/www/%1/cgi-bin

    <Directory "/var/www/*">
        Require all granted
        Options FollowSymLinks
        AllowOverride All
    </Directory>
</VirtualHost>

• %1 表示 Host 头中第一个点号前的部分（alice.example.com → alice）
• VirtualDocumentRoot /var/www/%1 就是映射根目录的核心指令
• ServerAlias *.example.com 不是必须，但建议加上，避免 Host 头异常时 fallback 到默认站点

---

如何支持三级及以上子域名（如 blog.dev.alice.example.com）

用 %2、%-1 等变量组合即可：

• blog.dev.alice.example.com 中：
  • %1 = blog
  • %2 = dev
  • %3 = alice
  • %-1 = com（最右段）
• 想让 dev.alice.example.com 映射到 /var/www/alice/dev/，可写：
  VirtualDocumentRoot /var/www/%3/%2

---

排查常见失败：403 或 404 不是模块问题

• 查 error log，开 LogLevel info，看 Apache 实际解析出的路径是否符合预期（日志里会打印 VirtualDocumentRoot is now /var/www/test）
• 确保目标目录存在，且父目录（如 /var/www/）对 Apache 用户有 x 权限（否则进不去）
• 若访问 example.com 本身没响应，注意 ServerAlias *.example.com 不匹配主域名，需单独加一个 ServerName example.com 的 <VirtualHost> 或用 ServerAlias example.com www.example.com 补充

不复杂但容易忽略