# 进阶配置

配置访问子路径、自定义品牌名称和 Logo。

部署说明 · 模块: deploy · 管理人员 · 部署形态：私有部署 · 已确认产品版本：资料未说明 · 来源：现有文档

私有部署默认挂在根路径、用 AskTable 自己的品牌。要把访问地址收进一个子路径（例如 `https://example.com/asktable`），或者换成自己公司的名字和 logo，改的都是主服务这个容器的环境变量和挂载。这些配置面向**已获取商业授权**的私有部署，授权方式见 [商业授权](https://docs.asktable.com/admin/license)。

## 前置条件

| 项目     | 要求                                                                   |
| ------ | -------------------------------------------------------------------- |
| 授权     | 已激活企业许可证，见 [商业授权](https://docs.asktable.com/admin/license)           |
| 基础部署   | 已按 [私有部署（Docker）](https://docs.asktable.com/deploy/docker) 跑起来并能正常登录 |
| 子路径部署  | 最外层网关能改写路径，或用下面的 Caddy 反代                                            |
| 白标资源   | 准备好 PNG 格式的 logo 与 favicon，放在宿主机上能读到的路径                              |
| 改动生效方式 | 环境变量和挂载都在容器启动时读取，改完必须 `docker compose up -d` 重建容器                    |

## 操作步骤

### 步骤 1：给主服务加 BASE\_PATH

在 `asktable` 服务的 `environment` 下加一行，值就是要用的路径前缀：

```yaml
services:
  asktable:
    environment:
      BASE_PATH: /asktable
```

### 步骤 2：加一个反代

反代负责把路径前缀剥掉再转给容器。用 Caddy 的话，在 compose 里加这个服务：

```yaml
services:
  caddy:
    image: caddy:2-alpine
    container_name: caddy
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
    depends_on:
      - asktable
```

同目录下新建 `Caddyfile`：

```text Caddyfile
:80 {
    redir /asktable /asktable/ permanent

    handle /asktable/* {
        uri strip_prefix /asktable
        reverse_proxy asktable:80
    }
}
```

改完通过 `http://服务器地址:8080/asktable/` 访问。生产环境一般把最外层网关接在 80/443 上，Caddy 这一层只在内部。

两处的路径前缀必须一致：`BASE_PATH` 和 Caddyfile 里的 `strip_prefix`。对不上会得到空白页或静态资源 404。

### 步骤 3：改品牌名

在 `asktable` 服务的 `environment` 下设置品牌信息：

```yaml
services:
  asktable:
    environment:
      APP_NAME: MyBrand          # 界面里的品牌名
      APP_TITLE: 我的应用         # 浏览器标签标题
      APP_DESCRIPTION: 应用描述   # 页面 meta description
```

### 步骤 4：换 logo 和 favicon

这两个文件由容器运行时按固定文件名读取，用卷挂载覆盖即可：

```yaml
services:
  asktable:
    volumes:
      - ./asktable_data:/asktable
      - ./mylogo.png:/usr/share/nginx/html/logo.png:ro
      - ./myfavicon.png:/usr/share/nginx/html/favicon.png:ro
```

`logo.png` 出现在侧边栏、登录页、二维码中心和分享页页头；`favicon.png` 是浏览器标签图标和 apple-touch-icon。

### 步骤 5：重建容器

```bash
docker compose up -d
```

品牌信息和访问前缀是在容器启动时写进前端配置的，只重启容器里的进程不会重新生成。

## 关键约束

| 项目                | 值或默认                                             | 在哪里改                                                   |
| ----------------- | ------------------------------------------------ | ------------------------------------------------------ |
| `BASE_PATH`       | 默认空，即根路径                                         | `asktable` 的 `environment`；改了必须重建容器                    |
| 前缀一致性             | `BASE_PATH` 与反代的 `strip_prefix` 必须相同             | 两处同时改                                                  |
| `APP_NAME`        | 默认 `AskTable`                                    | `asktable` 的 `environment`                             |
| `APP_NAME` 的连带影响  | 只要它不等于 `AskTable`，界面里的 AskTable 文档入口和「联系我们」会一并隐藏 | 无需额外配置，属预期行为                                           |
| `APP_TITLE`       | 默认沿用产品标题                                         | `asktable` 的 `environment`；留空则不替换                      |
| `APP_DESCRIPTION` | 默认沿用产品描述                                         | 同上                                                     |
| `logo.png`        | 应用内 logo                                         | 挂到 `/usr/share/nginx/html/logo.png`                    |
| `favicon.png`     | 浏览器标签图标                                          | 挂到 `/usr/share/nginx/html/favicon.png`                 |
| 前端错误上报            | `WEB_SENTRY_DSN` 为空时不初始化                         | `asktable` 的 `environment`，配套 `WEB_SENTRY_ENVIRONMENT` |
| 生效方式              | 环境变量与挂载在容器启动时读取                                  | `docker compose up -d` 重建容器                            |

## 出问题怎么判断

| 现象             | 判定条件                                    | 处理                                                          |
| -------------- | --------------------------------------- | ----------------------------------------------------------- |
| 子路径下页面空白       | 浏览器控制台里静态资源 404，请求路径缺了子路径前缀             | 检查 `BASE_PATH` 与 `strip_prefix` 是否一致，改完重建容器                 |
| 子路径访问 404      | 访问 `/asktable/` 返回 404，但容器本身是 `running` | Caddyfile 里 `reverse_proxy` 的目标要是 `asktable:80`，确认服务名和端口没写错 |
| 品牌名还是 AskTable | 页面上显示旧名字                                | `APP_NAME` 没生效，多半是没重建容器；`docker compose up -d` 后再看          |
| logo 位置出现裂图    | 浏览器里 `logo.png` 返回 403 或 404            | 挂载的宿主机文件不存在时 Docker 会建出同名目录，确认 `./mylogo.png` 是文件而不是目录      |
| 换了 logo 但界面没变  | 无痕窗口里仍显示旧图                              | 容器侧的挂载路径要正好是 `/usr/share/nginx/html/logo.png`，同时清掉浏览器缓存     |
| 文档入口突然消失       | `APP_NAME` 已改成非 `AskTable`              | 属预期行为：白标后 AskTable 自有品牌入口会隐藏                                |
| 改了环境变量没反应      | `docker compose ps` 里容器的创建时间还是改动前的      | 用了 `restart` 而不是重建；改成 `docker compose up -d`                |

## 下一步

- [商业授权](https://docs.asktable.com/admin/license) — 许可证层级与激活
- [私有部署（Docker）](https://docs.asktable.com/deploy/docker) — 部署参数与排障表
- [部署消息网关](https://docs.asktable.com/deploy/feishu-gateway) — 白标之后飞书侧的应用名要自己改
- [部署总览](https://docs.asktable.com/deploy/overview) — 可选组件与上线顺序