简介 #

本文档汇总 SmartChart 使用过程中的常见问题与解答（FAQ），涵盖安装启动、依赖库、数据集、图形配置等方面的典型问题及解决方案。

问题分类速查 #

常见问题 FAQ #

安装启动类 #

Q: 启动报错"以一种访问权限不允许的方式做了一个访问套接字的尝试"

Windows 中常见问题，端口被占用（酷狗音乐等软件会占用8000端口）：

netstat -ano|findstr 8000   # 找到占用的进程号
taskkill /pid 进程号 /F      # 强制终止进程

也可以换一个端口启动：smartchart runserver 0.0.0.0:8001 --insecure --noreload

Q: 输入命令找不到 smartchart

检查是否安装了多个 Python 环境导致环境变量冲突。可以：

• 卸载其中一个 Python 环境
• 或直接用完整路径运行：python -m smart_chart

Q: 无法安装 pip

安装 Python 时未勾选"Add to PATH"，请：

1. 重新安装 Python（勾选 Add to PATH）
2. 或手动将 Python 安装目录下的 Scripts 文件夹加入系统 PATH

Q: Mac 安装后各种问题（找不到命令等）

最大可能是系统 /Library/Developer/CommandLineTools 下残留了旧的 Python 3，与新安装的冲突：

# 先卸载旧版本
sudo rm -rf /Library/Developer/CommandLineTools
sudo rm -f /usr/bin/python3
# 再按文档重新安装 Python

确认完全卸载：命令行输入 python3 和 pip3，提示找不到命令才算干净。

Q: 忘记管理员密码

smartchart changepassword 你的用户名

依赖库类 #

Q: 安装时提示 urllib3 版本冲突

报错类似：<PACKAGE> depends on urllib3==2.0.0 时：

pip install urllib3==1.26.15

数据集类 #

Q: 数据集保存后图形数据没有更新

常见原因：

1. 数据集设置了缓存时间，需等待缓存过期或在 URL 中加 &refresh=Y 强制刷新
2. 数据集为懒加载模式，需要手动触发 ds_refresh()
3. SQL 查询本身没有返回新数据

Q: 参数联动后数据不变化

可能原因：

1. SQL 中的参数名（$参数名）与前端传的参数名不一致（注意大小写）
2. 数据集设置了缓存，带参数的数据集应将缓存时间设为 0

图形类 #

Q: 图形空白/不显示

检查步骤：

1. 打开浏览器 F12，查看 Console 是否有 JS 报错
2. 检查数据集是否有数据（在数据集编辑器执行查询）
3. 检查图形代码中的 __dataset__ 取值是否正确
4. 如果是多段查询，检查 dataset.df0 的格式是否正确