jeesa/tongtang-web repository overview

⁠同堂 Tongtang · 家庭智能控制台

基于 Home Assistant 的家庭成员权限控制台：给家人分配各自可见可控的设备，HomeKit 风格界面，支持多家庭、多 HA 实例、能源统计（电/燃气/水 + 表计层级下钻）、谁在家。内置互联平台：HomeKit（HA 桥 / 原生桥，PDU 等整机组合配件）、Matter 桥（一座桥同时接入苹果家庭 / Google Home / Alexa）、小爱同学、涂鸦——家人各自扫码配对，语音与第三方 App 的每次操作都经同堂权限校验并记入审计。支持 linux/amd64 与 linux/arm64。

完整文档与预置 compose（含 HomeKit/Matter 侧车开通注释开关）：https://github.com/ZHonry/tongtang⁠

⁠双容器部署（Nginx 前端 + API 后端）

前后端可独立更新，静态资源由 Nginx 服务：

name: tongtang

services:
  web:
    image: jeesa/tongtang-web:latest
    restart: unless-stopped
    ports:
      - "8080:80"
    depends_on:
      api:
        condition: service_healthy

  api:
    image: jeesa/tongtang-api:latest
    restart: unless-stopped
    environment:
      DATA_DIR: /data
      # ≥16 位随机字符串；启用 HomeKit/Matter 侧车时与侧车填同一个值
      APP_SECRET: "请自行生成一段足够长的随机字符串"
      INITIAL_ADMIN_PASSWORD: "admin123"
      TZ: "Asia/Shanghai"
      HA_URL: ""
      HA_TOKEN: ""
    volumes:
      - tongtang_data:/data
    extra_hosts:
      - "host.docker.internal:host-gateway"

networks:
  default:
    enable_ipv6: false

volumes:
  tongtang_data:

⁠镜像清单

⁠HomeKit / Matter 接入

HomeKit 原生桥与 Matter 桥以侧车容器开通——mDNS 广播要求 host 网络，适合 NAS / Linux Docker（Docker Desktop 不支持）。每种都有两种开通方式（api 挂 docker.sock 自动编排，或 compose 静态侧车），预置注释开关与完整说明见 GitHub 仓库⁠ 的 compose 与部署文档。Matter 桥使用开源测试 VID，添加配件时的「未认证配件」提示属正常现象。

⁠说明

• 数据（数据库、上传的图标/头像、HomeKit/Matter 配对）保存在 tongtang_data 卷中；升级执行 docker compose pull && docker compose up -d，数据与配对不丢
• 卷也可以换成宿主机目录（如 /mnt/zfs/Docker/tongtang/_data:/data）：容器启动时自动修正目录属主，无需手动 chown；可用环境变量 PUID/PGID 指定运行身份（默认 10001），设成你自己的 id -u/id -g 便于在宿主机直接读写数据文件
• APP_SECRET 用于会话签名，请每个部署使用不同的随机值