Excel 适合一次性分析，却不适合作为长期运营系统。随着数据源增加，常见问题会逐渐暴露：同一个“销售额”在不同文件中口径不同；报表依赖人工复制粘贴；筛选条件无法复用；历史数据和当前数据难以追踪；文件发给不该看到的人后，也很难撤回。
Metabase 可以把数据库中的查询、指标和可视化组织成可复用的问题与仪表盘。但“安装完成”并不等于“报表可持续运行”。真正需要设计的是数据模型、查询边界、权限规则和刷新机制。本文以一个包含订单、客户和商品表的业务库为例，搭建一套可维护的仪表盘，并讨论如何在需要时接入模型 API 生成辅助说明。
设计原则
先把报表拆成四层：
- 数据层：保留原始业务表，负责事实记录。
- 语义层：用视图或模型统一指标口径，例如已支付订单、净销售额和客单价。
- 展示层：仪表盘只消费经过验证的模型或问题，不直接拼接复杂业务逻辑。
- 解释层：模型 API 只负责对已筛选、已脱敏的结果进行归纳，不能替代数据库查询和权限判断。
其中最重要的一点是：模型生成的文字属于解释，不应成为事实来源。金额、数量、时间范围和权限都必须由数据库查询及应用逻辑确定。
准备数据模型
假设数据库中有以下表：orders、customers 和 products。订单表至少包含 id、customer_id、product_id、quantity、unit_price、status、paid_at 等字段。建议先创建一个只读视图，集中处理状态过滤和金额计算：
CREATE VIEW reporting_paid_orders AS
SELECT
o.id AS order_id,
o.customer_id,
o.product_id,
o.quantity,
o.unit_price,
o.quantity * o.unit_price AS gross_amount,
o.paid_at,
c.region,
p.category
FROM orders o
JOIN customers c ON c.id = o.customer_id
JOIN products p ON p.id = o.product_id
WHERE o.status = 'paid';
这里没有把“本月”“今年”等时间条件写死，因为时间范围应由仪表盘筛选器传入。若业务存在退款、折扣或税费，还应在视图中明确字段定义，避免展示层重复计算。
随后为报表账户授予最小权限。以下语句适用于支持相应权限模型的数据库，具体语法应以实际数据库为准：
CREATE USER metabase_reader WITH PASSWORD '${REPORT_DB_PASSWORD}';
GRANT CONNECT ON DATABASE analytics TO metabase_reader;
GRANT USAGE ON SCHEMA public TO metabase_reader;
GRANT SELECT ON reporting_paid_orders TO metabase_reader;
生产环境不应把密码直接写入脚本仓库。${REPORT_DB_PASSWORD} 只是占位符，部署时应通过密钥管理系统或运行环境注入。
用 Docker 运行 Metabase
最小化部署可以先使用 Docker Compose。下面的配置只演示 Metabase 应用容器，应用数据库建议使用独立的 PostgreSQL 或其他受支持数据库，而不要把容器内临时存储当作生产元数据存储：
services:
metabase:
image: metabase/metabase:latest
restart: unless-stopped
ports:
- "3000:3000"
environment:
MB_DB_TYPE: postgres
MB_DB_DBNAME: metabase
MB_DB_PORT: 5432
MB_DB_USER: ${
MB_DB_USER}
MB_DB_PASS: ${
MB_DB_PASS}
MB_DB_HOST: ${
MB_DB_HOST}
volumes:
- metabase_plugins:/plugins
volumes:
metabase_plugins:
不要在生产环境无审查地长期使用 latest。更稳妥的做法是根据官方发布信息选择经过验证的具体标签，并在升级前备份 Metabase 元数据库。首次启动后，使用管理界面添加分析数据库，连接账号使用上文的只读账户。
创建可复用指标
连接数据库后，不要立即为每个图表单独编写 SQL。先建立一个基础问题：
SELECT
paid_at::date AS business_date,
region,
category,
SUM(gross_amount) AS sales_amount,
COUNT(DISTINCT order_id) AS order_count,
SUM(gross_amount) / NULLIF(COUNT(DISTINCT order_id), 0) AS average_order_value
FROM reporting_paid_orders
WHERE paid_at >= {
{start_time}}
AND paid_at < {
{end_time}}
GROUP BY paid_at::date, region, category
ORDER BY business_date;
在 Metabase 中将 start_time 和 end_time 配置为日期或时间变量，并为字段设置清晰的显示名称与单位。时间条件使用左闭右开区间 >= start 且 < end，可以减少相邻日期或月份边界上的重复统计。
仪表盘可安排为四个区域：总销售额、订单数、客单价三个摘要指标；按日期的趋势图；按区域和品类的对比图；订单明细表。每个图表都绑定统一的时间筛选器，避免用户改变一个图表而忘记改变其他图表。
权限与数据隔离
权限至少要分为三类：
- 管理员：负责连接、模型和权限配置。
- 分析人员：可以创建问题和仪表盘，但不应自动拥有数据库写权限。
- 业务查看者：只能查看授权集合和仪表盘。
如果不同区域的人员只能查看本区域数据，不能只依靠前端筛选器。前端筛选器是交互条件，不是安全边界。应使用数据库行级安全能力、独立视图，或由后端根据登录身份生成受控查询。具体方案取决于数据库、Metabase 版本和部署方式，必须在目标环境验证。
同时避免把手机号、身份证号、邮箱等原始字段放进通用模型。报表通常只需要地区、客户等级或聚合后的客户数量。对必须使用的敏感字段，应在数据库层脱敏或建立专用视图。
刷新、缓存与稳定性
仪表盘刷新策略应根据数据延迟要求确定：
- 接近实时的运营看板，可以缩短缓存时间，但要评估数据库负载。
- 日报、周报等周期性报表，可以在数据同步完成后刷新。
- 大表查询应先确认时间过滤器能够下推，并检查过滤列、连接列和分组列的索引情况。
- 对不需要实时变化的聚合结果，可以建设日粒度汇总表或物化视图。
刷新失败时，先区分数据库连接失败、权限变化、查询超时和数据同步未完成。不要简单地无限增加超时时间，否则问题可能从可见的失败变成数据库连接池耗尽。应记录查询名称、触发时间、耗时、数据范围和错误类别，并为关键仪表盘设置外部监控。
接入模型 API 做结果解读
如果希望在仪表盘旁边显示“本期变化摘要”，建议把模型放在查询之后。后端先执行固定 SQL，只向模型发送聚合结果和明确任务，不发送数据库凭据、原始客户信息或不必要的明细。
const endpoint = process.env.MODEL_API_URL;
const apiKey = process.env.MODEL_API_KEY;
async function summarize(rows) {
const response = await fetch(`${
endpoint}/chat/completions`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${
apiKey}`
},
body: JSON.stringify({
model: process.env.MODEL_NAME,
temperature: 0,
messages: [
{
role: "system",
content: "只根据提供的统计结果生成简洁摘要；不补造原因，不输出未给出的数字。"
},
{
role: "user",
content: JSON.stringify({
period: "由服务端确定的统计周期",
metrics: rows
})
}
]
})
});
if (!response.ok) {
throw new Error(`model request failed: ${
response.status}`);
}
const data = await response.json();
return data.choices?.[0]?.message?.content ?? "暂无摘要";
}
该示例假设目标接口采用类似的请求结构，实际字段、模型名称、流式响应和错误格式必须以服务商当前文档为准。若评估 HaerAPI（https://www.haerapi.com）作为模型接入或中转接口，应先确认其当前 API 文档、数据处理条款、可用模型、限流规则和故障处理方式，再决定是否接入；密钥仍应只从环境变量或密钥系统读取。
模型输出进入页面前，还应做长度限制、敏感信息过滤和失败降级。若模型超时，仪表盘主体数据仍应正常展示，并将摘要区域标记为暂不可用。不要让模型响应决定 SQL、权限或导出范围。
常见问题
为什么图表数字和 Excel 不一致？
先比较统计周期、时区、订单状态、退款处理和去重规则，再比较 SQL。不要先修改图表格式。把指标定义写入模型说明或数据字典，并用几组人工核对样本验证边界日期。
只读账号是否足够？
对于只查询已授权视图的看板，通常可以作为基础方案，但仍要确认该账号不能创建函数、访问其他 schema 或读取敏感表。权限能力因数据库类型而异，应通过实际授权测试确认。
为什么要用视图而不是每张图单独写 SQL？
视图可以集中表达稳定的业务规则，减少重复逻辑。它不是万能方案：当查询需要复杂参数、跨库数据或高频聚合时，可能需要专用汇总表、ETL 或物化视图。
模型摘要出现了数据库中不存在的结论怎么办？
把提示词约束为“仅依据输入”，设置低随机性，并在服务端保留输入结果与模型响应。对关键数字由程序直接渲染，模型只生成变化描述。高风险场景还应加入人工审核或规则校验。
总结
从 Excel 迁移到 Metabase，核心不是把文件换成网页，而是建立可验证的数据链路：原始表负责记录，语义模型负责统一口径，仪表盘负责呈现，权限系统负责隔离，刷新和监控负责持续运行。模型 API 可以帮助解释已确定的统计结果，但不能替代查询、权限和审计。先把指标和边界定义清楚，再选择部署、缓存及模型接入方式，迁移后的报表才具备长期维护价值。
