{"id":51417326,"url":"https://github.com/cuckoo711/mijiaapi_v2","last_synced_at":"2026-07-04T21:00:29.178Z","repository":{"id":344069640,"uuid":"1180324235","full_name":"cuckoo711/mijiaAPI_V2","owner":"cuckoo711","description":"米家 API SDK V2 - 企业级 Python 智能家居控制库  采用现代化分层架构的米家设备控制 SDK，专为需要稳定可靠的企业级应用设计。 支持多用户并发、智能三层缓存、异步 API、完整类型注解，轻松集成到 Web 应用、 微服务、IoT 平台等复杂项目中。","archived":false,"fork":false,"pushed_at":"2026-07-04T20:01:25.000Z","size":733,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-04T20:11:01.261Z","etag":null,"topics":["api-client","async","cache-management","device-control","enterprise","home-automation","iot","layered-architecture","mijia","multi-user","python-sdk","python3","smart-home","xiaomi","xiaomi-smart","xiaomi-smart-home"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cuckoo711.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-12T23:36:27.000Z","updated_at":"2026-07-04T20:01:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cuckoo711/mijiaAPI_V2","commit_stats":null,"previous_names":["cuckoo711/mijiaapi_v2"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/cuckoo711/mijiaAPI_V2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuckoo711%2FmijiaAPI_V2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuckoo711%2FmijiaAPI_V2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuckoo711%2FmijiaAPI_V2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuckoo711%2FmijiaAPI_V2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cuckoo711","download_url":"https://codeload.github.com/cuckoo711/mijiaAPI_V2/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuckoo711%2FmijiaAPI_V2/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35135342,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","async","cache-management","device-control","enterprise","home-automation","iot","layered-architecture","mijia","multi-user","python-sdk","python3","smart-home","xiaomi","xiaomi-smart","xiaomi-smart-home"],"created_at":"2026-07-04T21:00:20.642Z","updated_at":"2026-07-04T21:00:29.074Z","avatar_url":"https://github.com/cuckoo711.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 米家 API SDK \u0026 Server\n\n[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/downloads/)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n\n米家智能家居 Python SDK，内置 FastAPI + Vue3 管理后台。\n\n**两种使用形态：**\n\n| 形态 | 说明 |\n|------|------|\n| **SDK** | 在 Python 项目中直接调用米家登录、设备控制、场景执行等能力 |\n| **API Server** | 部署为本地/服务器服务，通过网页管理，对外提供 HTTP API |\n\n\u003e 管理台默认监听 `127.0.0.1:8123`，公网使用需开启访问开关并建议搭配 HTTPS 反向代理。\n\n## 快速部署\n\n### 环境要求\n\n- Python 3.9+ / uv\n- Node.js 18+ / npm\n\n### 一键启动\n\n```bash\ngit clone git@github.com:cuckoo711/mijiaAPI_V2.git\ncd mijiaAPI_V2\n\n# 安装依赖 \u0026 构建前端\nuv sync \u0026\u0026 cd web \u0026\u0026 npm ci \u0026\u0026 npm run build \u0026\u0026 cd ..\n\n# 初始化 \u0026 启动\nuv run python -m server.cli init\nuv run python -m server.cli run\n```\n\n打开 `http://127.0.0.1:8123` → 创建管理员 → 扫码登录米家 → 同步家庭/设备/场景 → 开始使用。\n\n### 首次使用流程\n\n1. 打开管理台，创建管理员账号\n2. 进入「米家登录」，用米家 App 扫码\n3. 点击「同步家庭/设备/场景」（支持实时进度显示）\n4. 进入「API Key」创建调用密钥\n5. 使用 API 接入你的应用\n\n## 核心功能\n\n| 功能 | 说明 |\n|------|------|\n| 扫码登录 | 米家 App 扫码，凭据自动保存和刷新 |\n| 设备管理 | 家庭/设备列表、状态查询、隐藏/只读控制 |\n| 场景控制 | 场景列表、一键执行、权限管理 |\n| API Key | 创建/启停/删除，细粒度权限控制 |\n| 实时同步进度 | 同步时显示进度条、步骤、设备/场景计数 |\n| 安全策略 | 局域网/公网开关、可信代理、审计日志 |\n\n## 对外 API\n\n```bash\n# 基本用法\ncurl -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  http://127.0.0.1:8123/api/v1/devices\n```\n\n| 方法 | 路径 | 说明 |\n|------|------|------|\n| `GET` | `/api/v1/status` | 服务状态 |\n| `GET` | `/api/v1/homes` | 家庭列表 |\n| `GET` | `/api/v1/devices` | 设备列表 |\n| `GET` | `/api/v1/devices/{slug}/state` | 设备状态 |\n| `POST` | `/api/v1/devices/{slug}/properties` | 控制设备 |\n| `POST` | `/api/v1/devices/{slug}/actions` | 执行动作 |\n| `GET` | `/api/v1/scenes` | 场景列表 |\n| `POST` | `/api/v1/scenes/{id}/execute` | 执行场景 |\n| `GET` | `/api/v1/logs` | 审计日志 |\n\n管理台「API 使用」页面有完整的请求示例和参数说明。交互式文档（Swagger/ReDoc）可在「系统安全」中开启。\n\n## SDK 使用\n\n```python\nfrom mijiaAPI_V2 import create_api_client_from_file\n\n# 加载凭据并创建客户端\napi = create_api_client_from_file()\n\n# 获取家庭和设备\nhomes = api.get_homes()\ndevices = api.get_devices(homes[0].id)\n\n# 控制设备\napi.control_device(device_id=devices[0].did, siid=2, piid=1, value=True)\n```\n\n更多示例见 `examples/` 目录。\n\n## 环境变量\n\n| 变量 | 默认值 | 说明 |\n|------|--------|------|\n| `MIJIA_SERVER_HOST` | `127.0.0.1` | 监听地址 |\n| `MIJIA_SERVER_PORT` | `8123` | 监听端口 |\n| `MIJIA_SERVER_DATA_DIR` | `.mijia/server` | 数据目录 |\n| `MIJIA_CREDENTIAL_PATH` | `.mijia/credential.json` | 凭据文件 |\n| `MIJIA_LOG_LEVEL` | `INFO` | 日志级别（支持 `DEBUG`） |\n\n## 部署\n\n### systemd\n\n```ini\n[Unit]\nDescription=Mijia API Server\nAfter=network-online.target\n\n[Service]\nType=simple\nWorkingDirectory=/opt/mijia_server\nExecStart=/usr/bin/env uv run python -m server.cli run\nRestart=always\n\n[Install]\nWantedBy=multi-user.target\n```\n\n### Nginx 反向代理\n\n```nginx\nserver {\n    listen 443 ssl http2;\n    server_name miapi.example.com;\n    ssl_certificate /path/to/fullchain.pem;\n    ssl_certificate_key /path/to/privkey.pem;\n\n    location / {\n        proxy_pass http://127.0.0.1:8123;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n    }\n}\n```\n\n## 项目结构\n\n```\nmijiaAPI_V2/\n├── mijiaAPI_V2/        # SDK 核心\n│   ├── api_client.py   # API 客户端\n│   ├── core/           # 配置、日志\n│   ├── domain/         # 领域模型\n│   ├── repositories/   # 数据仓储\n│   ├── services/       # 业务服务\n│   └── infrastructure/ # HTTP、缓存、加密\n├── server/             # FastAPI 服务端\n│   ├── app.py          # 路由和鉴权\n│   ├── mijia_runtime.py # SDK 桥接层\n│   └── store.py        # SQLite 读写\n├── web/                # Vue3 管理后台\n├── examples/           # 11 个示例\n├── docs/               # 详细文档\n├── build.py            # 多平台构建脚本\n├── build.sh            # Linux/macOS 构建脚本\n├── build.bat           # Windows 构建脚本\n└── mijia-server.spec   # PyInstaller 配置\n```\n\n## 打包为可执行文件\n\n项目支持打包为独立可执行文件，无需安装 Python 即可运行。\n\n### 本地构建\n\n```bash\n# 安装构建工具\nuv pip install pyinstaller\n\n# 构建前端\ncd web \u0026\u0026 npm ci \u0026\u0026 npm run build \u0026\u0026 cd ..\n\n# 构建可执行文件\nuv run pyinstaller --clean --noconfirm mijia-server.spec\n\n# 输出目录: dist/mijia-server/\n```\n\n### 多平台构建\n\n项目支持以下平台的自动构建：\n\n| 平台 | 架构 | 输出格式 |\n|------|------|----------|\n| Windows | x64 | ZIP |\n| Linux | x64 | TAR.GZ |\n| Linux | ARM64 | TAR.GZ |\n| macOS | x64 | TAR.GZ |\n| macOS | ARM64 | TAR.GZ |\n\n推送版本标签后会自动触发 GitHub Actions 构建：\n\n```bash\ngit tag v2.1.0\ngit push origin v2.1.0\n```\n\n### 运行可执行文件\n\n```bash\n# 解压后直接运行\n./mijia-server init\n./mijia-server run\n```\n\n默认监听 `127.0.0.1:8123`。\n\n## 常见问题\n\n**同步按钮可以连续点吗？** 前端会禁用按钮，后端返回 `409 SYNC_IN_PROGRESS`。\n\n**API 返回 `NETWORK_ACCESS_DENIED`？** 需在「系统安全」开启局域网/公网请求。\n\n**API Key 创建后还能查看完整密钥吗？** 不能，只在创建时显示一次。\n\n**支持 Docker 吗？** 支持，核心只需 Python、Node 和 SQLite。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcuckoo711%2Fmijiaapi_v2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcuckoo711%2Fmijiaapi_v2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcuckoo711%2Fmijiaapi_v2/lists"}