米家智能家居 Python SDK，内置 FastAPI + Vue3 管理后台。
两种使用形态：
| 形态 | 说明 |
|---|---|
| SDK | 在 Python 项目中直接调用米家登录、设备控制、场景执行等能力 |
| API Server | 部署为本地/服务器服务，通过网页管理，对外提供 HTTP API |
管理台默认监听
127.0.0.1:8123，公网使用需开启访问开关并建议搭配 HTTPS 反向代理。
- Python 3.9+ / uv
- Node.js 18+ / npm
git clone git@github.com:cuckoo711/mijiaAPI_V2.git
cd mijiaAPI_V2
# 安装依赖 & 构建前端
uv sync && cd web && npm ci && npm run build && cd ..
# 初始化 & 启动
uv run python -m server.cli init
uv run python -m server.cli run打开 http://127.0.0.1:8123 → 创建管理员 → 扫码登录米家 → 同步家庭/设备/场景 → 开始使用。
- 打开管理台，创建管理员账号
- 进入「米家登录」，用米家 App 扫码
- 点击「同步家庭/设备/场景」（支持实时进度显示）
- 进入「API Key」创建调用密钥
- 使用 API 接入你的应用
| 功能 | 说明 |
|---|---|
| 扫码登录 | 米家 App 扫码，凭据自动保存和刷新 |
| 设备管理 | 家庭/设备列表、状态查询、隐藏/只读控制 |
| 场景控制 | 场景列表、一键执行、权限管理 |
| API Key | 创建/启停/删除，细粒度权限控制 |
| 实时同步进度 | 同步时显示进度条、步骤、设备/场景计数 |
| 安全策略 | 局域网/公网开关、可信代理、审计日志 |
# 基本用法
curl -H "Authorization: Bearer YOUR_API_KEY" \
http://127.0.0.1:8123/api/v1/devices| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/api/v1/status |
服务状态 |
GET |
/api/v1/homes |
家庭列表 |
GET |
/api/v1/devices |
设备列表 |
GET |
/api/v1/devices/{slug}/state |
设备状态 |
POST |
/api/v1/devices/{slug}/properties |
控制设备 |
POST |
/api/v1/devices/{slug}/actions |
执行动作 |
GET |
/api/v1/scenes |
场景列表 |
POST |
/api/v1/scenes/{id}/execute |
执行场景 |
GET |
/api/v1/logs |
审计日志 |
管理台「API 使用」页面有完整的请求示例和参数说明。交互式文档（Swagger/ReDoc）可在「系统安全」中开启。
from mijiaAPI_V2 import create_api_client_from_file
# 加载凭据并创建客户端
api = create_api_client_from_file()
# 获取家庭和设备
homes = api.get_homes()
devices = api.get_devices(homes[0].id)
# 控制设备
api.control_device(device_id=devices[0].did, siid=2, piid=1, value=True)更多示例见 examples/ 目录。
| 变量 | 默认值 | 说明 |
|---|---|---|
MIJIA_SERVER_HOST |
127.0.0.1 |
监听地址 |
MIJIA_SERVER_PORT |
8123 |
监听端口 |
MIJIA_SERVER_DATA_DIR |
.mijia/server |
数据目录 |
MIJIA_CREDENTIAL_PATH |
.mijia/credential.json |
凭据文件 |
MIJIA_LOG_LEVEL |
INFO |
日志级别（支持 DEBUG） |
[Unit]
Description=Mijia API Server
After=network-online.target
[Service]
Type=simple
WorkingDirectory=/opt/mijia_server
ExecStart=/usr/bin/env uv run python -m server.cli run
Restart=always
[Install]
WantedBy=multi-user.targetserver {
listen 443 ssl http2;
server_name miapi.example.com;
ssl_certificate /path/to/fullchain.pem;
ssl_certificate_key /path/to/privkey.pem;
location / {
proxy_pass http://127.0.0.1:8123;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}mijiaAPI_V2/
├── mijiaAPI_V2/ # SDK 核心
│ ├── api_client.py # API 客户端
│ ├── core/ # 配置、日志
│ ├── domain/ # 领域模型
│ ├── repositories/ # 数据仓储
│ ├── services/ # 业务服务
│ └── infrastructure/ # HTTP、缓存、加密
├── server/ # FastAPI 服务端
│ ├── app.py # 路由和鉴权
│ ├── mijia_runtime.py # SDK 桥接层
│ └── store.py # SQLite 读写
├── web/ # Vue3 管理后台
├── examples/ # 11 个示例
├── docs/ # 详细文档
├── build.py # 多平台构建脚本
├── build.sh # Linux/macOS 构建脚本
├── build.bat # Windows 构建脚本
└── mijia-server.spec # PyInstaller 配置
项目支持打包为独立可执行文件，无需安装 Python 即可运行。
# 安装构建工具
uv pip install pyinstaller
# 构建前端
cd web && npm ci && npm run build && cd ..
# 构建可执行文件
uv run pyinstaller --clean --noconfirm mijia-server.spec
# 输出目录: dist/mijia-server/项目支持以下平台的自动构建：
| 平台 | 架构 | 输出格式 |
|---|---|---|
| Windows | x64 | ZIP |
| Linux | x64 | TAR.GZ |
| Linux | ARM64 | TAR.GZ |
| macOS | x64 | TAR.GZ |
| macOS | ARM64 | TAR.GZ |
推送版本标签后会自动触发 GitHub Actions 构建：
git tag v2.1.0
git push origin v2.1.0# 解压后直接运行
./mijia-server init
./mijia-server run默认监听 127.0.0.1:8123。
同步按钮可以连续点吗？ 前端会禁用按钮，后端返回 409 SYNC_IN_PROGRESS。
API 返回 NETWORK_ACCESS_DENIED？ 需在「系统安全」开启局域网/公网请求。
API Key 创建后还能查看完整密钥吗？ 不能，只在创建时显示一次。
支持 Docker 吗？ 支持，核心只需 Python、Node 和 SQLite。