Skip to content

cuckoo711/mijiaAPI_V2

BranchesTags

Repository files navigation

米家 API SDK & Server

Python Version License

米家智能家居 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 → 创建管理员 → 扫码登录米家 → 同步家庭/设备/场景 → 开始使用。

首次使用流程

  1. 打开管理台，创建管理员账号
  2. 进入「米家登录」，用米家 App 扫码
  3. 点击「同步家庭/设备/场景」（支持实时进度显示）
  4. 进入「API Key」创建调用密钥
  5. 使用 API 接入你的应用

核心功能

功能 说明
扫码登录 米家 App 扫码，凭据自动保存和刷新
设备管理 家庭/设备列表、状态查询、隐藏/只读控制
场景控制 场景列表、一键执行、权限管理
API Key 创建/启停/删除，细粒度权限控制
实时同步进度 同步时显示进度条、步骤、设备/场景计数
安全策略 全站网络 ACL、可信代理（默认关）、Cookie+CSRF、审计日志、凭据加密
管理改密 管理台改密 + CLI reset-admin

对外 API

# 基本用法
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 设备列表（可选 include_spec / include_raw）
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）可在「系统安全」中开启。

SDK 使用

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 configs 数据目录
MIJIA_SERVER_DATABASE_PATH configs/server/server.sqlite3 SQLite 路径
MIJIA_CREDENTIAL_PATH configs/credential.json 凭据文件（AES-GCM 加密）
MIJIA_WEB_DIST_DIR web/dist 前端静态资源
MIJIA_LOG_LEVEL INFO 日志级别（支持 DEBUG）
MIJIA_BOOTSTRAP_ALLOW_PRIVATE 空 1 时允许私网完成首次建管理员（Docker）
MIJIA_CREDENTIAL_SECRET 空 可选凭据加密密钥；不设则用 .credential_key

也可编辑 configs/server.toml（可用 python -m server.cli write-config 生成）；环境变量优先。

常用 CLI

uv run python -m server.cli init
uv run python -m server.cli run
uv run python -m server.cli check
uv run python -m server.cli status          # 版本 / 路径 / 磁盘占用
uv run python -m server.cli reset-admin     # 本机重置管理员密码
uv run python -m server.cli purge-audit
uv run python -m server.cli purge-cache     # 可加 --all
uv run python -m server.cli write-config

部署

Docker

docker compose -f deploy/docker-compose.yml up -d --build

数据与凭据持久化在命名卷 mijia-data（可在 deploy/docker-compose.yml 中改为绑定 ./data:/data）。首次启动后访问 http://127.0.0.1:8123 创建管理员。可选初始化：

docker compose -f deploy/docker-compose.yml run --rm mijia-server mijia-server init --admin admin

更多说明见 deploy/README.md。

systemd

仓库提供加固示例单元，见 deploy/mijia-server.service 与 deploy/mijia-server.env.example。

sudo cp deploy/mijia-server.service /etc/systemd/system/
sudo cp deploy/mijia-server.env.example /etc/mijia-server.env
# 按需修改路径与 User=
sudo systemctl daemon-reload
sudo systemctl enable --now mijia-server

默认仅监听 127.0.0.1。若经 Nginx 反代并需要按真实客户端 IP 做网络策略，请在管理台开启 TRUST_PROXY_HEADERS，并正确配置 TRUSTED_PROXY_CIDRS。

Nginx 反向代理

server {
    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 核心
├── server/                # FastAPI 服务端
├── web/                   # Vue3 管理台
├── configs/               # 运行时数据与 TOML 模板
├── docs/ · examples/ · tests/
├── deploy/                # Docker / systemd / 打包 / 运维脚本
│   ├── Dockerfile
│   ├── docker-compose.yml
│   ├── packaging/         # build 脚本与 mijia-server.spec
│   ├── scripts/           # clean / release notes / 设备规格工具
│   └── assets/            # 应用图标
├── pyproject.toml · Makefile · README.md
└── .dockerignore          # 需在仓库根（Docker build context）

管理台使用 HttpOnly Cookie 会话 + CSRF；对外 API 仍用 Authorization: Bearer <api_key>。 SDK 与 Server 默认数据目录均为 configs/（旧 .mijia/ 启动时迁移后删除）。 详见 docs/开发指南/05-API-Server-开发启动.md。

打包为可执行文件

项目支持打包为独立可执行文件，无需安装 Python 即可运行。

本地构建

# 安装构建工具
uv pip install pyinstaller pillow

# 一键构建（前端 + 可执行文件）
uv run python deploy/packaging/build.py

# 或分步：
cd web && npm ci && npm run build && cd ..
uv run pyinstaller --clean --noconfirm deploy/packaging/mijia-server.spec

输出目录：dist/。

多平台构建

项目支持以下平台的自动构建：

平台 架构 输出格式
Windows x64 ZIP
Linux x64 TAR.GZ
Linux ARM64 TAR.GZ
macOS x64 TAR.GZ
macOS ARM64 TAR.GZ

推送版本标签后会自动触发 GitHub Actions 构建：

git tag v3.7.3
git push origin v3.7.3

运行可执行文件

# 解压后直接运行
./mijia-server init
./mijia-server run

默认监听 127.0.0.1:8123。

常见问题

同步按钮可以连续点吗？ 前端会禁用按钮，后端返回 409 SYNC_IN_PROGRESS；进度接口按 task_id 区分轮次。

API 返回 NETWORK_ACCESS_DENIED？ 需在「系统安全」开启局域网/公网请求。策略覆盖管理台与对外 API。

API Key 创建后还能查看完整密钥吗？ 不能，只在创建时显示一次。

忘记管理员密码？ 本机执行 python -m server.cli reset-admin。

管理台登录态存在哪？ HttpOnly Cookie（mijia_admin_session）+ CSRF；不要跨域依赖 Cookie。

支持 Docker 吗？ 支持：docker compose -f deploy/docker-compose.yml up -d --build，详见 deploy/README.md。

About

米家 API SDK V2 - 企业级 Python 智能家居控制库 采用现代化分层架构的米家设备控制 SDK，专为需要稳定可靠的企业级应用设计。 支持多用户并发、智能三层缓存、异步 API、完整类型注解，轻松集成到 Web 应用、 微服务、IoT 平台等复杂项目中。

Topics

home-automation enterprise iot async api-client python3 smart-home multi-user xiaomi python-sdk xiaomi-smart layered-architecture mijia xiaomi-smart-home cache-management device-control

Resources

Readme

License

MIT license
Activity

Stars

8 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 24

v3.7.3 Latest
Jul 20, 2026
+ 23 releases

Packages

 
 
 

Contributors

Languages