Skip to content

World's first open-source enterprise world model.

A half-mounted source should say so, not report failure (#144)

WaylandYang9e92690ffcb9
diff --git a/crates/utopia-server/src/alerting.rs b/crates/utopia-server/src/alerting.rs
index 5277a979..0f12ed64 100644
--- a/crates/utopia-server/src/alerting.rs
+++ b/crates/utopia-server/src/alerting.rs
@@ -71,3 +71,44 @@ pub fn spawn_retention_sweep(state: AppState) {
}
});
}
+
+/// 数据源挂上了,库表结构却没摄进来。
+///
+/// **报的不是那次失败,是它留下的状态。** 挂载分两步:写 `kb_data_sources`,
+/// 再把 schema 生成文档摄进库。第一步成了、第二步没成的时候,源是真挂着的——
+/// `query_data` 会入列,而模型检索不到任何表结构,只能瞎猜列名。
+///
+/// 挂载那一刻的报错只有点按钮的人看得见。此后这个库就一直静默地缺着,
+/// 而这正是 0009 说的那件事:真正伤人的不是失败,是失败无声。
+pub async fn observe_schema_sync_failure(
+ state: &AppState,
+ kb_id: uuid::Uuid,
+ source_id: uuid::Uuid,
+ source_name: &str,
+ err: &anyhow::Error,
+) {
+ if let Err(e) = alerts::raise(
+ &state.pool,
+ alerts::NewAlert {
+ kb_id: Some(kb_id),
+ severity: "warning",
+ kind: alerts::kind::SCHEMA_SYNC_FAILED,
+ // 配置类:要修的是连接串或网络,不是内容。找 admin
+ min_role: Role::Admin,
+ subject_type: Some("data_source"),
+ subject_id: Some(source_id),
+ // 名字在这里存一份——源被删掉之后 subject_id 解析不出名字,
+ // 而告警该留得住
+ detail: serde_json::json!({
+ "source": source_name,
+ "error": err.to_string(),
+ }),
+ },
+ )
+ .await
+ {
+ tracing::warn!(error = %e, "上报 data_source.schema_sync_failed 失败");
+ return;
+ }
+ state.emit_alert();
+}
diff --git a/crates/utopia-server/src/api/datasource_routes.rs b/crates/utopia-server/src/api/datasource_routes.rs
index 8c9e5507..9a3e9e82 100644
--- a/crates/utopia-server/src/api/datasource_routes.rs
+++ b/crates/utopia-server/src/api/datasource_routes.rs
@@ -135,10 +135,33 @@ pub async fn mount(
}
utopia_store::datasources::mount(&state.pool, kb_id, ds_id).await?;
// 挂载即摄取 schema:Chat 写 SQL 前能检索到表结构
- let synced = sync_schema_doc(&state, kb_id, ds_id)
+ //
+ // **这一步失败不能回报成挂载失败。** 上面那行已经写进 kb_data_sources 了,
+ // 源是真挂着的;从前这里 `?` 出去回 500,人以为没挂上,实际挂上了——
+ // 而问数看不见它有哪些表。改成:照实说挂载成了,schema 没成,并且
+ // 报进告警中心,因为那之后就是一个静默的缺失状态(0009)
+ match sync_schema_doc(&state, kb_id, ds_id).await {
+ Ok(synced) => Ok(Json(json!({ "ok": true, "schema_tables": synced }))),
+ Err(e) => {
+ let name = source_name(&state, ds_id).await;
+ crate::alerting::observe_schema_sync_failure(&state, kb_id, ds_id, &name, &e).await;
+ Ok(Json(json!({
+ "ok": true,
+ "schema_tables": 0,
+ "schema_error": e.to_string(),
+ })))
+ }
+ }
+}
+
+/// 告警要留住名字:源被删之后 `subject_id` 就解析不出名字了。查不到时给占位符
+/// 而不是让告警本身失败——**报警路径上的失败不该淹掉它要报的那件事**。
+async fn source_name(state: &AppState, ds_id: Uuid) -> String {
+ utopia_store::datasources::list(&state.pool)
.await
- .map_err(AppError::Other)?;
- Ok(Json(json!({ "ok": true, "schema_tables": synced })))
+ .ok()
+ .and_then(|all| all.into_iter().find(|d| d.id == ds_id).map(|d| d.name))
+ .unwrap_or_else(|| ds_id.to_string())
}
pub async fn unmount(
@@ -151,16 +174,25 @@ pub async fn unmount(
Ok(Json(json!({ "ok": true })))
}
+/// 手动刷新结构。
+///
+/// **这里照旧把错误回给调用方**——点按钮的人正看着,而且什么都没半途发生。
+/// 但同样报一条告警:留下的后果与挂载失败时一模一样(源挂着、表结构是旧的
+/// 或空的),而点按钮的人未必是需要知道这件事的人。
pub async fn sync_schema(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path((kb_id, ds_id)): Path<(Uuid, Uuid)>,
) -> ApiResult<Json<serde_json::Value>> {
require_kb(&state, &user, kb_id, Role::Admin).await?;
- let synced = sync_schema_doc(&state, kb_id, ds_id)
- .await
- .map_err(AppError::Other)?;
- Ok(Json(json!({ "ok": true, "schema_tables": synced })))
+ match sync_schema_doc(&state, kb_id, ds_id).await {
+ Ok(synced) => Ok(Json(json!({ "ok": true, "schema_tables": synced }))),
+ Err(e) => {
+ let name = source_name(&state, ds_id).await;
+ crate::alerting::observe_schema_sync_failure(&state, kb_id, ds_id, &name, &e).await;
+ Err(AppError::Other(e).into())
+ }
+ }
}
/// Agentic 探索:后台任务读挂载源 schema,提议 指标/维度→字段 映射(低置信入 Review)。
diff --git a/crates/utopia-store/src/alerts.rs b/crates/utopia-store/src/alerts.rs
index 2d156289..a500c01c 100644
--- a/crates/utopia-store/src/alerts.rs
+++ b/crates/utopia-store/src/alerts.rs
@@ -27,6 +27,12 @@ pub mod kind {
/// 系统级:模型端点没给出可用的回答——连不上,或者连上了但回来的不是这个 API。
/// 端点干净地回 4xx 不算:那说明它就是模型 API,只是密钥或配额不对
pub const LLM_UNREACHABLE: &str = "llm.unreachable";
+ /// 库级:数据源挂上了,它的库表结构却没摄进来。`min_role = admin`
+ ///
+ /// **这一条描述的不是那次失败,是它留下的状态**:源挂着,而问数看不见它有
+ /// 哪些表——`query_data` 照样入列,模型却只能瞎猜列名。挂载那一刻的报错
+ /// 只有点按钮的人看得见,此后这个库就一直这样静默地缺着。
+ pub const SCHEMA_SYNC_FAILED: &str = "data_source.schema_sync_failed";
}
/// 一次故障。打包成结构体不只是为了参数个数——调用点写 `severity: "error"`
diff --git a/web/src/api.ts b/web/src/api.ts
index 67db3b63..7c3c9ae6 100644
--- a/web/src/api.ts
+++ b/web/src/api.ts
@@ -1085,13 +1085,16 @@ export const api = {
request<{ data_sources: DataSourceView[] }>(
`/api/v1/kbs/${kbId}/data-sources/available`,
),
+ /** 挂载。**`schema_error` 非空时挂载仍然成了**——源是真挂上的,只是它的
+ * 库表结构没摄进来,问数看不见有哪些表。同一件事会进告警中心 */
mountDataSource: (kbId: string, dsId: string) =>
- request<{ ok: boolean; schema_tables: number }>(
- `/api/v1/kbs/${kbId}/data-sources/${dsId}`,
- {
- method: "PUT",
- },
- ),
+ request<{
+ ok: boolean;
+ schema_tables: number;
+ schema_error?: string | null;
+ }>(`/api/v1/kbs/${kbId}/data-sources/${dsId}`, {
+ method: "PUT",
+ }),
unmountDataSource: (kbId: string, dsId: string) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/data-sources/${dsId}`, {
method: "DELETE",
diff --git a/web/src/i18n/en.ts b/web/src/i18n/en.ts
index 359ebfa7..4660cfed 100644
--- a/web/src/i18n/en.ts
+++ b/web/src/i18n/en.ts
@@ -150,6 +150,10 @@ export const en = {
title: "A source failed to sync",
hint: "Nothing new came in from it. Check the source's settings.",
},
+ "data_source.schema_sync_failed": {
+ title: "A data source is mounted, but its schema is not",
+ hint: "Ask cannot see which tables exist, so it will guess column names. Check the connection, then use Refresh schema.",
+ },
"llm.unreachable": {
title: "The model endpoint gave no usable answer",
hint: "Extraction and embedding are stopped. Check the endpoint URL in system settings.",
@@ -1059,6 +1063,10 @@ export const en = {
unmount: "Unmount",
syncSchema: "Refresh schema",
schemaSynced: (n: number) => `Schema ingested (${n} tables)`,
+ // Mounted, schema did not. **Do not call this a failed mount** — the source is mounted
+ schemaFailed:
+ "The data source is mounted, but its schema could not be ingested — Ask cannot see which tables exist. " +
+ "This is in the alert centre; check the connection, then use Refresh schema.",
explore: "Explore mappings",
exploreHint:
"An agent reads these schemas and proposes metric and dimension definitions. Proposals land in Pending; Ask uses them only once confirmed.",
diff --git a/web/src/i18n/zh.ts b/web/src/i18n/zh.ts
index 9b1ef840..769ffeea 100644
--- a/web/src/i18n/zh.ts
+++ b/web/src/i18n/zh.ts
@@ -132,6 +132,10 @@ export const zh: Strings = {
title: "来源同步失败",
hint: "它没有带进新内容。去来源设置里看一下。",
},
+ "data_source.schema_sync_failed": {
+ title: "数据源挂上了,库表结构没进来",
+ hint: "问数看不见有哪些表,只能猜列名。检查连接串,然后点「刷新结构」。",
+ },
"llm.unreachable": {
title: "模型端点没有给出可用的回答",
hint: "抽取与向量化已停摆。去系统设置里检查端点地址。",
@@ -952,6 +956,10 @@ export const zh: Strings = {
unmount: "卸载",
syncSchema: "刷新结构",
schemaSynced: (n: number) => `结构已摄入(${n} 张表)`,
+ // 挂载成了、结构没成。**别说成失败**——源是真挂上的
+ schemaFailed:
+ "数据源已挂载,但库表结构没能摄入——问数看不见有哪些表。已报进告警中心;" +
+ "检查连接串后点「刷新结构」重试。",
explore: "探查映射",
exploreHint:
"一个智能体读这些库表结构,提出指标/维度的口径。提出来的落在「待审批」,确认之后问数才会用。",
diff --git a/web/src/pages/Mappings.tsx b/web/src/pages/Mappings.tsx
index f5df50a9..f965b0bb 100644
--- a/web/src/pages/Mappings.tsx
+++ b/web/src/pages/Mappings.tsx
@@ -450,14 +450,21 @@ function DataSources({
});
const [picked, setPicked] = useState("");
const [notice, setNotice] = useState<string | null>(null);
+ // 与 notice 分开:一个是「成了」,一个是「成了一半」,配色也不同
+ const [warning, setWarning] = useState<string | null>(null);
const invalidate = () =>
queryClient.invalidateQueries({ queryKey: ["kbDataSources", kbId] });
const mount = useMutation({
mutationFn: (dsId: string) => api.mountDataSource(kbId, dsId),
+ // **挂载成了、schema 没成,是两件事。** 服务端此时回的是 ok(源确实挂上了),
+ // 所以不能照着 `schema_tables: 0` 说「已摄入 0 张表」——那等于说成功了。
+ // 说清楚半成的是哪一半,同一件事也进了告警中心
onSuccess: (r) => {
setPicked("");
- setNotice(S.mapping.schemaSynced(r.schema_tables));
+ setNotice(null);
+ setWarning(r.schema_error ? S.mapping.schemaFailed : null);
+ if (!r.schema_error) setNotice(S.mapping.schemaSynced(r.schema_tables));
invalidate();
},
onError: (e: unknown) => toast.error((e as Error).message),
@@ -582,6 +589,9 @@ function DataSources({
</div>
)}
{notice && <p className="text-xs text-[var(--u-ok)]">{notice}</p>}
+ {warning && (
+ <p className="text-xs text-[var(--u-warn)]">{warning}</p>
+ )}
</div>
);
}