常见问题

本节整理了 SmartTable 在部署和使用过程中可能遇到的常见问题及解决方案。如果这里没有覆盖到你的问题，可以通过右上角「问题反馈」入口或 GitHub Issue 联系我们。

部署与安装

Docker 部署后无法访问首页

现象：运行 docker run 后，浏览器访问 http://localhost 提示拒绝连接或 502 错误。

解决方案：

1. 确认容器是否正常启动：docker ps 查看容器状态是否为 Up。
2. 查看容器日志：docker logs <container_id>，检查是否有端口被占用或启动报错。
3. 确认映射端口正确，例如 -p 80:80 表示将容器 80 端口映射到宿主机 80 端口。
4. 如果 80 端口被占用，可更换为其他端口，如 -p 8080:80，然后访问 http://localhost:8080。
5. 检查防火墙或安全组是否放行了对应端口。

Windows 启动包双击 start.bat 后闪退

现象：双击 start.bat 后黑色窗口一闪而过，服务没有启动。

解决方案：

1. 不要直接双击，改为在 PowerShell 或 CMD 中运行 start.bat，这样能看到完整报错信息。
2. 检查是否被杀毒软件拦截，可将启动包目录加入白名单。
3. 确认路径中不含中文或特殊字符，建议放到纯英文路径下运行。
4. 查看 logs/ 目录下的日志文件，定位具体错误。

后端日志提示 Redis 连接失败

现象：启动时报 ConnectionError 或 Redis is not running。

解决方案：

1. Docker 部署已内嵌 Redis，若手动部署需单独安装并启动 Redis。
2. 检查 .env 或环境变量中的 REDIS_URL 是否配置正确。
3. 如果不需要实时协作功能，可在系统设置中关闭协作开关，或设置 COLLABORATION_ENABLED=false。
4. 使用 redis-cli ping 测试 Redis 是否可达。

PostgreSQL 模式下表创建失败或迁移报错

现象：切换到 PostgreSQL 后出现 relation does not exist 或迁移失败。

解决方案：

1. 确认数据库已提前创建，且用户拥有创建表和扩展的权限。
2. 首次启动时 Alembic 会自动执行迁移，确保运行目录正确（应在 smarttable-backend 目录下执行）。
3. 若迁移版本不一致，可手动执行 flask db upgrade。
4. 检查 DATABASE_URL 格式是否正确，例如：postgresql://user:pass@host:5432/dbname。

登录与权限

登录后不久就提示"登录已过期"

现象：使用一段时间后刷新页面，被跳转回登录页。

解决方案：

1. v1.6.3 已支持 Token 自动续期，请确认前端和后端版本一致且已升级到 v1.6.3。
2. 检查系统设置中的「会话超时时间」，默认值较短，可按需调整为合适的值（不建议超过 7 天）。
3. 如果使用的是反向代理，确认代理没有过滤或缓存 JWT 相关请求头。
4. 清除浏览器缓存后重新登录。

注册入口找不到或无法注册

现象：登录页没有「注册」按钮，或点击注册提示「注册已关闭」。

解决方案：

1. 管理员可在「系统管理 → 系统设置」中开启或关闭注册功能。
2. 若关闭注册，只能由管理员在后台手动创建用户。
3. 检查当前登录用户是否为管理员角色。

表格与字段

公式字段显示"#ERROR"或计算结果不对

现象：配置了公式字段后，单元格显示错误或不计算。

解决方案：

1. 检查公式语法是否正确，建议使用字段配置面板中的「公式助手」辅助编写。
2. 确认引用的字段名称或字段 ID 没有变更，变更后需重新编辑公式。
3. v1.6.3 统一了前后端公式函数注册，升级后若仍报错，请检查是否使用了尚未支持的函数。
4. 数字、日期等字段类型在公式中会自动转换，注意类型匹配。

关联/查找字段数据不刷新或显示错位

现象：关联字段选择后，查找字段没有同步更新，或显示旧数据。

解决方案：

1. v1.6.3 已修复关联字段缓存不刷新的问题，请先升级到最新版本。
2. 刷新页面或重新打开记录抽屉。
3. 检查关联字段的关系类型配置是否正确，关系类型变更后需要重新保存字段。
4. 确认查找字段引用的目标字段在关联记录中存在有效值。

新增记录时一次出现两行

现象：点击「添加记录」后，表格中多出了两行空白记录。

解决方案：

1. 这是 v1.6.3 已修复的编辑器回调异常问题，升级即可解决。
2. 如果升级后仍出现，请检查浏览器控制台是否有报错，并通过「问题反馈」入口提交。

数字字段默认总是 0

现象：数字字段未填写时自动显示 0。

解决方案：

1. v1.6.3 优化了数字字段默认值规则，会根据字段默认值设置自动判断写 0 还是写空值。
2. 如需自定义，可在字段配置中设置「默认值」为空或具体数值。
3. 同时检查数字字段的「小数位」设置是否生效。

视图与交互

看板视图拖拽卡片后分组没变

现象：在看板中拖动卡片到另一列，刷新后卡片回到原列。

解决方案：

1. v1.6.3 已修复看板拖拽未使用目标分组 ID 的问题，升级即可。
2. 确认拖拽到的列对应的分组字段值与卡片目标值一致。
3. 检查当前用户是否有该数据表的编辑权限。

表格数据量大时加载很慢

现象：记录数上万时，表格首屏加载需要几秒甚至更久。

解决方案：

1. SmartTable 支持流式加载，首屏优先加载部分数据，后台异步加载剩余页。
2. 减少单页显示数量，或在视图中配置合适的筛选条件。
3. 为常用查询字段建立索引（PostgreSQL 模式下效果更明显）。
4. 关闭不必要的实时协作功能，减少 WebSocket 数据传输。

附件上传失败或无法预览

现象：点击上传附件没有反应，或上传后缩略图不显示。

解决方案：

1. 检查附件字段的「文件数量限制」和「文件大小限制」，单个文件默认不超过 10MB。
2. 确认上传目录有写入权限，Docker 部署需持久化存储卷。
3. v1.6.3 支持单击缩略图直接预览完整图片，若无法预览请检查浏览器是否拦截了弹窗。
4. 查看后端日志，确认是否有 MIME 类型或文件内容安全校验失败的记录。

工作流

工作流保存后没有触发

现象：配置了触发器和节点，但记录创建/更新后工作流没有执行。

解决方案：

1. 确认工作流状态为「运行中」，已暂停或草稿状态不会触发。
2. 检查触发器的过滤条件是否配置正确，注意 AND/OR 逻辑。
3. 确认触发器监听的字段是否在更新时实际发生了变化。
4. 查看「执行日志」，确认是否有报错或节点执行失败。

循环节点没有执行或数据为空

现象：循环节点状态显示跳过，或循环体没有执行。

解决方案：

1. 确认循环数据源类型配置正确：
   • 遍历查找记录的全部结果时，类型应选 find_records_all。
   • 提取某个字段的多值时，类型应选 find_records_column。
2. 检查查找记录节点是否返回了有效数据。
3. 循环体中的节点 ID 必须在保存时正确映射为后端 UUID。
4. 查看执行日志中的 skipped_reason、data_array 等诊断信息。

Webhook 节点收不到请求

现象：工作流执行显示成功，但对方系统没有收到 Webhook。

解决方案：

1. 检查 Webhook URL 是否正确，是否包含多余空格。
2. 查看「Webhook 投递日志」，确认请求是否发出、响应状态码是多少。
3. 确认对方服务器能够访问 SmartTable 所在网络（内网部署时尤其注意）。
4. 检查 Webhook 请求头、请求体模板是否正确渲染，避免变量解析失败导致请求被丢弃。

实时协作

在线用户不显示或协作状态异常

现象：多人同时编辑时看不到其他用户，或锁定状态不同步。

解决方案：

1. 确认实时协作功能已开启，且 Redis 服务正常运行。
2. 检查浏览器控制台是否有 WebSocket 连接失败的报错。
3. 如果使用了反向代理或 Nginx，确认已正确配置 WebSocket 转发（/socket.io/ 路径）。
4. v1.6.3 已修复时区获取逻辑，支持读取浏览器本地时区，避免因时区不一致导致的协同异常。

邮件与通知

邮件发送失败

现象：配置了 SMTP 后，测试发送或工作流邮件节点发送失败。

解决方案：

1. 检查 SMTP 服务器地址、端口、加密方式（TLS/SSL）和认证信息。
2. 确认邮箱已开启 SMTP 服务，部分邮箱需要单独开启授权码。
3. 查看邮件发送日志，检查是否被邮件服务商拦截或进入垃圾箱。
4. 如果使用企业邮箱，确认没有发送频率限制或 IP 白名单限制。

性能与浏览器

页面卡顿或浏览器崩溃

现象：打开大数据表或复杂仪表盘时浏览器变卡甚至崩溃。

解决方案：

1. 减少同时展开的视图和仪表盘组件数量。
2. 为大数据表配置合适的筛选条件，避免一次性加载全量数据。
3. 使用 Chrome、Edge 等现代浏览器，并保持浏览器为较新版本。
4. 关闭浏览器中不常用的扩展插件，避免内存占用过高。

其他

时区显示不对

现象：日期时间字段显示的时间与预期不一致。

解决方案：

1. 在「系统管理 → 系统设置」中配置正确的系统时区。
2. 若时区模式为「本地时区」，会优先使用配置的 timezone_name；未配置时使用浏览器本地时区。
3. 若时区模式为「UTC」，所有时间将以 UTC 展示。
4. 切换时区后建议刷新页面使配置生效。

如何提交 Bug 或功能建议

解决方案：

1. 点击系统右上角「问题反馈」入口，填写问题描述并附上截图和日志。
2. 前往 GitHub Issues 提交：https://github.com/ldbinac/smart_table/issues
3. 关注微信公众号「程序员吕洞宾」获取最新动态。