东营昕睿信息科技GIS · 智慧园区 · 地下管网 · 嵌入式
预约演示

故障排查

星火赋能平台本地部署与联调故障排查：启动失败、端口占用与数据“消失”

要点速览

星火赋能平台联调时最常见的三类问题：启动时没加 -f net8.0 导致“面向多个框架”报错；旧实例或其它程序占用 5005 / 1883 端口导致整个后端启动失败；在 bin 目录下启动进程导致 SQLite 连到一个新的空库，看起来像数据丢失。按本文逐项核对基本都能定位。

这篇面向在本机或测试服务器上部署、联调星火赋能平台的开发与运维人员。问题标题尽量使用你看到的报错原文或现象，按标题检索即可。环境搭建步骤见快速入门。

启动失败 #

提示“你的项目面向多个框架，请指定要使用 --framework 运行的框架” #

这不是环境问题，启动命令加上 -f net8.0（或 -f net10.0）即可。

平台后端、以及解决方案中的其它可执行工程都同时面向 net8.0 与 net10.0 两个目标框架，单独执行 dotnet run 时 .NET 无法判断用哪个。正确写法：

bash
dotnet run -f net8.0

-f 是 --framework 的简写，两者等价。

SocketException (10048) 端口已被占用，随后 Hosting failed to start #

最常见的原因是本机已经有一个后端实例在运行，它同时占用着 API 端口（本地默认 5005）和内置 MQTT 端口（默认 1883）。

处理方法：

  1. 查找占用端口的进程。Windows 下可以用 netstat -ano 并筛选 :5005，Linux 下可以用 ss -lntp 或 lsof -i :5005；
  2. 确认是上次没停干净的旧实例后，结束该进程；
  3. 重新启动后端。

只启动了一个后端实例，仍然启动失败 #

检查 1883 端口是否被其它 MQTT 服务（如 Mosquitto、EMQX 或其它项目）占用。

后端内置的 MQTT 服务默认开启，端口 1883；MQTT 绑定失败会导致整个后端启动失败，而不仅仅是 MQTT 不可用。在 Windows 上 1883 还可能落在系统动态保留端口段，偶发冲突。处理方法二选一：

  • 修改应用层配置目录下 Mqtt.json 的 Port；
  • 不需要 MQTT 时，把 Mqtt.json 中的 Enabled 设为 false。

日志中出现 Cannot open log for source '.NET Runtime'. You may not have write access. #

这条不是启动失败的原因，真正的原因在它上面几行。

在受限账户或受限沙箱中运行时，进程尝试写 Windows 事件日志被拒绝，就会出现这条信息。它只在启动已经失败之后作为“记录失败日志”的二次异常出现。向上查看日志，通常能找到端口占用等真正原因。

前端 pnpm run dev 提示 8888 端口被占用 #

上一次的开发服务没有退出干净，找到占用 8888 的进程并结束即可。

同样的方法适用于其它前端开发端口。

数据与账号 #

刚创建的数据或账号突然“消失”了 #

大概率是进程工作目录变了，连到了另一个 SQLite 库。

使用 SQLite 时，连接串是相对路径（默认 DataSource=./Sepe.Net.db），从哪个目录启动进程，就使用哪个目录下的库。如果先进入 bin/Debug/net8.0 再运行可执行文件，平台会在该目录下新建一个空库，日志和接口都正常，但数据和之前的不是同一份。

排查方法：在项目目录下递归搜索 *.db 文件，看是否存在多个库。以后统一在项目目录（Sepe.Net.Web.Entry）下启动进程。正式环境建议使用 MySQL、PostgreSQL 等服务端数据库，或把 SQLite 连接串改为明确的绝对路径。

重启后种子数据会不会覆盖我改过的数据？ #

不会覆盖用户等标记为只补不覆盖的数据。

平台每次启动都会增量补齐种子数据：缺表建表、缺记录插入；带 [IncreSeed] 的种子按 Id 更新；带 [IgnoreUpdateSeed] 的实体（如用户表）只插入缺失记录，不改写已有记录，因此改过的密码不会被还原。

想把本地环境恢复到初始状态怎么办？ #

停止后端进程，删除库文件后重新启动，平台会重建全部表并写入种子数据。

使用 SQLite 时删除项目目录下的 Sepe.Net.db* 文件（包括同名的附属文件）；使用其它数据库时清空对应的库。此操作会丢失全部数据，正式环境不要这样做。

登录与接口 #

管理后台登录页能打开，但登录或接口请求失败 #

先确认后端是否在运行，以及前端代理指向的地址是否正确。

  1. 访问 http://localhost:5005/api/sysConfig/smPublicKey，返回 code 为 200 说明后端正常；
  2. 检查 Web/.env.development 中 VITE_API_URL 是否指向实际的后端地址；开发模式下 Vite 会把 /api 代理到该地址；
  3. 正式部署时检查 Web 服务器是否把 /api 正确反向代理到后端。

直接从其它页面或域名调用后端接口被跨域拦截 #

在后端 App.json 的跨域配置 CorsAccessorSettings.WithOrigins 中加入允许的来源。

平台默认的跨域配置较为宽松，便于本地调试；上线前必须收紧，只保留正式的管理后台域名。

官网与社区组件（如交付包含） #

如果你的交付内容包含基于 Nuxt 的官网与社区站点，以及为它提供接口的用户站点服务（本地默认端口 3000 与 5015），还可能遇到下面几个问题。

官网登录或社区接口返回 502 #

官网连不上用户站点服务，先确认 http://127.0.0.1:5015/healthz 是否返回 200。

不是 200 就先把用户站点服务启动起来（同样需要 -f net8.0）。另外注意启动顺序：用户站点库由后端管理服务首次启动时建表并写入种子数据，用户站点服务自身不建表；库不存在时它会直接连接失败。所以首次部署要先启动一次后端，再启动用户站点服务，之后谁先启动都可以。

官网登录后一直显示未登录 #

检查浏览器地址与官网配置的站点地址是否统一使用 localhost（或统一使用 127.0.0.1）。

localhost 与 127.0.0.1 对浏览器来说是两个不同的站点，不会共享 Cookie。还可以直接打开官网的 /api/member-session，正常应返回 {"member":null}（未登录）而不是网络错误。

用管理后台账号登录官网提示“账号或密码不正确” #

这是预期行为：官网会员与管理后台员工是两套完全独立的账号体系，互相不能登录。

官网会员需要在官网自行注册。

后台修改了社区设置，官网没有立即生效 #

用户站点服务对社区设置有缓存，默认最多 60 秒后生效。

联调时如需立即看到效果，可以调小用户站点服务配置中的社区设置缓存时间并重启服务。

仍未解决的问题，可以带上完整日志到技术社区提问，或通过联系我们反馈。