-
Notifications
You must be signed in to change notification settings - Fork 5
FAQ
确保网络可以访问 PyPI。mijiaAPI 3.0+ 会作为依赖自动安装。如果安装失败，尝试：
pip install --upgrade pip
pip install mijiaAPI>=3.0
pip install -e ".[dev]"确保在项目根目录（mijia-control/）下运行命令，且虚拟环境已激活。
检查 .env 文件是否正确配置：
- 确认
.env文件存在于项目根目录 - 检查
DATABASE_URL中的用户名、密码、主机和端口 - 确认 MySQL 服务已启动
- 确认数据库已创建：
mysql -u root -p -e "SHOW DATABASES LIKE 'mijia';"
常见原因：
- 数据库不存在 → 先创建数据库（见 Installation）
- 连接信息错误 → 检查
.env中的DATABASE_URL - 权限不足 → 确认 MySQL 用户有 CREATE/ALTER 权限
激活虚拟环境后命令才可用：
venv\Scripts\activate
mijia-control --help或将 venv\Scripts 目录添加到系统 PATH。
- 确保使用小米账号（非小米商城账号）扫码
- 使用米家 App 扫码，不要用微信/支付宝扫
- 二维码有效期约 5 分钟，超时后重新生成
- 确认米家 App 中设备在线
- 尝试强制刷新：Web UI 中点击刷新按钮，或 API 加
?refresh=true - 首次同步可能需要几秒钟
小米账号 Token 会定期过期，系统会自动尝试续期。如果持续失败：
- Web UI 中解绑小米账号
- 重新扫码绑定
- 米家云端数据有缓存，尝试 API 加
?refresh=true强制刷新 - 网络延迟可能导致短暂不一致，稍后重试
部分属性是只读的（如传感器数据、设备状态）。通过以下方式查看可写属性：
# CLI 查看设备完整规格
mijia-control device show <did>
# 或 API
GET /api/devices/<did>返回的 spec 中会标注每个属性的读写权限。
- 确认设备在线且网络正常
- 部分设备响应较慢，重试一次
- 蓝牙设备需要网关附近才能控制
- 确认 go2rtc 服务已启动并正确配置
- 检查
.env中的GO2RTC_URL是否正确 - 参考
go2rtc.yaml.example配置摄像头信息
需要先获取 JWT Token 并设置为环境变量：
mijia-control login
# 然后设置环境变量
export MIJIA_TOKEN=$(cat ~/.config/mijia-control/token.json | python -c "import sys,json;print(json.load(sys.stdin)['token'])")详见 HomeKit Bridge。
- 确保手机和电脑在同一局域网
- Windows 用户需安装 Bonjour Print Services
- 确认端口 51826 未被占用
- 尝试手动输入 PIN 码
123-45-678
创建 homekit_mapping.yaml 手动指定：
devices:
你的设备model: light # 可选: light, outlet, switch, thermostat, heater, ignored修改后重启 Bridge 即可生效，不需要重新配对。
Bridge 会自动从 spec_data 发现正确的属性名。如果设备缺少 spec_data，Bridge 会自动调用详情 API 补充。确保 Flask API 服务正常运行。
HomeKit → 米家的控制是实时的，米家 → HomeKit 的状态同步依赖 10 秒间隔的轮询，延迟约 3-10 秒，属于正常现象。
不需要。配对信息保存在 homekit.state 文件中。只要此文件存在，重启后自动恢复配对。如果删除了此文件，则需要重新配对。
# 查看端口占用（Linux/Mac）
lsof -i :51826
# Windows
netstat -ano | findstr 51826或修改 .env 中的 HOMEKIT_PORT 使用其他端口。
- access_token：24 小时
- refresh_token：7 天
Token 过期后使用 refresh_token 获取新的 access_token：
curl -X POST http://127.0.0.1:5000/api/auth/jwt/refresh \
-H "Authorization: Bearer <refresh_token>"触发了限流保护。默认限制：
- 全局：200 次/天，50 次/小时
- 登录/注册：5 次/分钟
等待一段时间后重试，或联系管理员调整限流配置。
确保 FLASK_ENV 不为 testing（测试环境禁用 Swagger）。访问地址：
http://127.0.0.1:5000/api/docs/
# 使用 gunicorn + eventlet worker
pip install gunicorn eventlet
gunicorn --worker-class eventlet -w 1 -b 0.0.0.0:5000 "app:create_app()[0]"建议配合 Nginx 反向代理，启用 HTTPS。
在 Nginx 配置 SSL 证书，反向代理到 Flask：
server {
listen 443 ssl;
server_name your-domain.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://127.0.0.1:5000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
# SocketIO 支持
location /socket.io/ {
proxy_pass http://127.0.0.1:5000/socket.io/;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}配置已内置连接池管理（config/__init__.py）：
-
pool_recycle=3600— 每小时回收连接 -
pool_pre_ping=True— 使用前检测连接有效性
如果仍有连接超时，检查 MySQL 的 wait_timeout 配置。
底层使用 mijiaAPI，支持所有在米家平台上注册的设备。具体可用的属性和动作取决于设备型号，可通过 device show 命令查看。
支持。每个用户独立绑定自己的小米账号，设备数据互不干扰。管理员可通过后台管理用户。
- 用户数据、Token、自动化规则等：MySQL 数据库
- CLI Token：
~/.config/mijia-control/token.json - 小米账号认证数据：数据库中的
auth_data字段 - 设备规格缓存：
instance/spec_cache/目录
# 备份 MySQL 数据库
mysqldump -u root -p mijia > mijia_backup_$(date +%Y%m%d).sql
# 恢复
mysql -u root -p mijia < mijia_backup_20260502.sql- 查看服务日志输出
- 在 GitHub Issues 搜索或提交问题
- 提交 Issue 时请附上：错误信息、
.env配置（去除密钥）、操作步骤
返回 Home。