Message-Push-Nest/docs/guide/url-prefix.md

URL 前缀配置

Message Nest 支持配置 URL 前缀，允许您将应用部署在子路径下（例如 /message-nest），而不是根路径。

工作原理

配置 URL 前缀后：

1. 后端会在所有路由前添加指定的前缀
2. 前端页面加载时，后端会在 HTML 中自动注入前缀配置
3. 前端的所有 API 请求会自动使用该前缀

无需手动配置前端，前后端会自动同步！

使用场景

• 在同一域名下部署多个应用
• 通过反向代理（如 Nginx）将应用映射到子路径
• 在企业内网中统一管理多个服务

配置方式

方式一：配置文件

编辑 conf/app.ini 文件，在 [server] 部分添加：

[server]
RunMode = release
HttpPort = 8000
UrlPrefix = /message-nest

方式二：环境变量

设置环境变量：

export URL_PREFIX=/message-nest

或在 Docker 中：

docker run -e URL_PREFIX=/message-nest ...

配置说明

• 路径格式：可以带或不带前导斜杠 /，系统会自动处理
• 示例值：
  • /message-nest
  • /api/message-nest
  • message-nest（会自动转换为 /message-nest）
• 默认值：空字符串（部署在根路径）

访问方式

配置 URL 前缀后，访问地址会变为：

• 原地址：http://your-domain.com/
• 新地址：http://your-domain.com/message-nest/

所有 API 端点也会自动添加前缀：

• 原 API：http://your-domain.com/api/v1/sendways/list
• 新 API：http://your-domain.com/message-nest/api/v1/sendways/list

Nginx 反向代理配置示例

如果使用 Nginx 反向代理，配置示例：

location /message-nest/ {
    proxy_pass http://localhost:8000/message-nest/;
    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;
}

注意事项

::: warning 注意

1. 修改配置后需要重启服务才能生效
2. 前后端会自动同步前缀配置，后端会在 HTML 中注入配置
3. 已有的 API 调用会自动适配新的前缀
4. 静态资源（CSS、JS、图片等）也会自动使用新的前缀
5. 开发模式下，如果前端单独运行，需要确保后端 API 的前缀配置正确 :::

常见问题

Q: 修改前缀后无法访问？

A: 请检查：

1. 是否已重启服务
2. 前缀格式是否正确
3. 如果使用反向代理，检查代理配置是否正确

Q: 可以使用多级路径吗？

A: 可以，例如：/api/message-nest 或 /services/messaging/nest

Q: URL 前缀会影响性能吗？

A: 不会，URL 前缀只是路径的一部分，不会影响应用性能。

示例

示例 1：部署在子路径

# conf/app.ini
[server]
UrlPrefix = /message-nest

访问地址：http://your-domain.com/message-nest/

示例 2：多级子路径

# conf/app.ini
[server]
UrlPrefix = /api/services/message-nest

访问地址：http://your-domain.com/api/services/message-nest/

示例 3：Docker 环境变量

docker run -d \
  -p 8000:8000 \
  -e URL_PREFIX=/message-nest \
  -e DB_TYPE=sqlite \
  message-nest:latest

访问地址：http://localhost:8000/message-nest/