内容
# Apache Superset 6.1.0 部署包
基于官方预构建镜像,含中文汉化 + MCP 服务。容器自启策略由 `.env` 的 `RESTART_POLICY` 控制:本机测试设 `no`(不自启),服务器设 `unless-stopped`(开机自启)。
## 文件结构
```
.
├── .env # 环境变量(3 个必改项,见下)
├── docker-compose.yml # 编排文件
├── po2jed.py # 翻译再生工具(改完 .po 后用)
└── docker/
├── docker-entrypoint-initdb.d/
│ └── init-superset-db.sh # Postgres 初始化(建 examples 库)
├── pythonpath_dev/
│ └── superset_config.py # Superset 配置(含中文 LANGUAGES)
└── translations/zh/LC_MESSAGES/
├── messages.po # 中文翻译源文件(可编辑)
└── messages.json # 前端加载的翻译(由 po2jed.py 生成)
```
## 服务器部署
### 前置条件
服务器需已安装 Docker 和 Docker Compose:
```bash
docker --version # 需要 20+
docker compose version # 需要 v2+
```
### 部署步骤
**1. 上传整个目录到服务器**
把 `.env`、`docker-compose.yml`、`po2jed.py`、`docker/` 全部传到服务器同一目录。
**2. 编辑 `.env`,改 3 个必改项**
```bash
vim .env
```
需要修改(文件里有 `[必改]` 标注):
| 变量 | 说明 | 本机测试 | 服务器 |
|------|------|----------|--------|
| `REGISTRY_MIRROR` | 镜像加速器。直连 Docker Hub 留空;国内服务器填加速器 | `docker.m.daocloud.io/` | `docker.m.daocloud.io/` |
| `SUPERSET_SECRET_KEY` | 生产密钥,必须换随机值 | 随意 | 运行 `openssl rand -base64 42` 生成 |
| `ADMIN_PASSWORD` | 管理员密码 | `admin` | 改强密码 |
| `RESTART_POLICY` | 容器自启策略 | `no`(不自启) | `unless-stopped`(开机自启) |
可选(端口被占用时改):
```env
SUPERSET_PORT=8088 # Superset Web 端口
MCP_PORT=5008 # MCP 服务端口
```
**3. 启动**
```bash
docker compose up -d
```
首次启动较慢(需初始化数据库 + 加载示例数据,约 3-5 分钟)。
查看初始化进度:
```bash
docker logs -f superset_init # 看到 "Complete" 即初始化成功
```
**4. 访问**
```
http://服务器IP:8088
用户名: admin
密码: .env 里的 ADMIN_PASSWORD(默认 admin)
```
切换中文:登录后访问 `http://服务器IP:8088/lang/zh`,或右上角语言选择器选 Chinese。
## 功能说明
### 中文汉化
- 前端通过 `/superset/language_pack/zh/` 端点加载翻译(4050 条)
- 翻译源文件:`docker/translations/zh/LC_MESSAGES/messages.po`
- 发现某处翻译不准时,编辑 `.po` 后重新生成:
```bash
# 在容器内执行 po2jed.py 重新生成 messages.json
docker exec -i superset_app python - < po2jed.py
# 重启 app 容器(前端会重新 fetch)
docker compose restart superset
```
### MCP 服务(给 AI 调用)
- 端点:`http://服务器IP:5008/mcp`(streamable-http 协议)
- 让 AI 客户端(Claude/Cursor 等)通过 MCP 操作 Superset:查数据集、生成图表、执行 SQL、建仪表盘等
- **生产级安全**:采用自定义 API Key 认证,无 key 或 key 错误一律 401 拒绝
#### API Key(配一次永久有效)
MCP 认证用固定 API Key(替代会过期的 JWT token)。`.env` 里已预置一个:
```env
MCP_API_KEY=ui_6g8ltD4JPW8ZWZgBdhUTNmL8h5zYFYAd-zBT8oltjiv6S3ahNa_0d
```
重新生成自己的密钥(生产环境建议换):
```bash
python -c "import secrets; print(secrets.token_urlsafe(42))"
```
#### 客户端连接(带 API Key)
客户端配置(Claude Desktop / Cursor 等),把 API Key 填入 headers:
```json
{
"mcpServers": {
"superset": {
"url": "http://服务器IP:5008/mcp",
"type": "http",
"headers": {
"Authorization": "Bearer <你的 MCP_API_KEY>"
}
}
}
}
```
API Key 永不过期,配一次长期有效。换 key 只需改 `.env` 的 `MCP_API_KEY` 后重启 mcp 容器:
```bash
docker compose restart superset-mcp
```
## 常用命令
```bash
docker compose up -d # 启动(不会自启,需手动执行)
docker compose down # 停止(保留数据)
docker compose down -v # 停止并清空所有数据
docker compose logs -f superset # 看 Superset 日志
docker compose ps # 查看容器状态
```
## 服务清单
| 容器 | 端口 | 作用 |
|------|------|------|
| superset_app | 8088 | Superset Web 服务 |
| superset_mcp | 5008 | MCP 服务(AI 调用) |
| superset_worker | - | Celery 异步任务 |
| superset_worker_beat | - | Celery 定时任务 |
| superset_db | - | PostgreSQL 17 元数据库 |
| superset_cache | - | Redis 缓存 |
所有容器的自启策略由 `.env` 的 `RESTART_POLICY` 决定:
- 本机测试 `RESTART_POLICY=no`:重启电脑后不自动启动,需手动 `docker compose up -d`
- 服务器 `RESTART_POLICY=unless-stopped`:**开机自动启动**
## 故障排查
**启动失败,看日志:**
```bash
docker compose logs superset_init # 初始化失败
docker compose logs superset # app 启动失败
```
**镜像拉不动(超时):**
- 确认 `.env` 的 `REGISTRY_MIRROR` 设置正确
- 国内服务器用 `docker.m.daocloud.io/` 或 `docker.1ms.run/`
- 测试连通性:`curl -I https://docker.m.daocloud.io/v2/`
**worker 启动失败(缺 psycopg2):**
- 正常现象,compose 已配置自动补装,等待 30-60 秒即可
- 查看:`docker logs superset_worker`
**端口被占用:**
```bash
# 改 .env 里的 SUPERSET_PORT 或 MCP_PORT,然后:
docker compose up -d
```
**重置全部数据重来:**
```bash
docker compose down -v
docker compose up -d
```
