jeesa/tongtang 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⁠

⁠快速开始（一体化，单容器）

将以下内容保存为 docker-compose.yml，然后执行 docker compose up -d，打开 http://主机IP:8080 按向导连接 Home Assistant。

name: tongtang

services:
  tongtang:
    image: jeesa/tongtang:latest
    restart: unless-stopped
    ports:
      - "8080:8000"          # 改左边可换访问端口
    environment:
      DATA_DIR: /data
      # 会话签名密钥：≥16 位随机字符串（openssl rand -hex 32 生成）；
      # 若启用 HomeKit/Matter 侧车，api 与侧车必须填同一个值
      APP_SECRET: "请自行生成一段足够长的随机字符串"
      INITIAL_ADMIN_PASSWORD: "admin123"   # 首次管理员密码，登录后请立即修改
      TZ: "Asia/Shanghai"
      # HA 跑在本机时可填 http://host.docker.internal:8123；留空则走网页首次配置向导
      HA_URL: ""
      HA_TOKEN: ""
    volumes:
      - tongtang_data:/data
    extra_hosts:
      - "host.docker.internal:host-gateway"

networks:
  default:
    enable_ipv6: false   # 规避 IPv6 半通导致的间歇性无响应

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 用于会话签名，请每个部署使用不同的随机值