charleslee1120/koix-homiary repository overview

⁠Homiary

面向个人与家庭的资产库存管理系统。像日记一样记录每件资产的购买、转移、维修、借出、归还和处置历史。

界面为简体中文，自带管理后台，无需额外依赖即可运行 —— 默认使用容器内的 SQLite，也可以在初始化时切换到外部 PostgreSQL。

⁠支持的标签

可用版本与发布说明见 https://koix.org/products/homiary⁠。

均为多架构镜像，支持 linux/amd64 与 linux/arm64，docker pull 时自动匹配当前平台。

⁠快速开始

docker run -d --name koix-homiary -p 3000:3000 -v koix-homiary-data:/data --restart unless-stopped charleslee1120/koix-homiary:latest

浏览器访问 http://<服务器地址>:3000，首次会自动跳转到 /setup，在页面上选择数据库并创建管理员账号。

⁠docker compose

services:
  homiary:
    image: charleslee1120/koix-homiary:latest
    container_name: koix-homiary
    ports:
      - "3000:3000"
    volumes:
      - koix-homiary-data:/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/api/system/status').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

volumes:
  koix-homiary-data:

镜像基于 node:22-bookworm-slim，不含 curl 和 wget，健康检查请使用 Node 自带的 fetch，常见的 CMD curl -f ... 写法在本镜像中无法工作。

⁠数据持久化

容器内 /data 存放全部持久状态，必须挂载，否则容器重建后数据丢失：

推荐使用命名卷。若改用宿主目录绑定挂载，需要先把目录属主改成容器内的运行用户 —— 镜像以非 root 的 node 用户运行，uid 与 gid 均为 1000：

sudo mkdir -p /srv/homiary/data && sudo chown -R 1000:1000 /srv/homiary/data

属主不正确时容器仍能启动，但初始化会因为无权写入数据目录而失败。

⁠环境变量

SMTP、备份周期、提醒规则等均在应用的 /settings 页面配置并写入数据库，不通过环境变量传入。

⁠使用 PostgreSQL

在 /setup 页面选择 PostgreSQL 并填写连接地址即可，连接串写入 /data/system.json，不走环境变量。数据库需要提前创建，并确保容器网络可达 —— 使用 compose 时把数据库与应用放在同一网络，连接地址填服务名而不是 localhost。

⁠升级与回滚

docker compose pull && docker compose up -d

数据保存在卷中，升级不受影响。建议升级前先在 /settings 手动备份一次。需要回滚时把 image 的标签指定为上一个版本号，再执行 up -d。

⁠备份

应用自身会按 /settings 中配置的周期与保留天数自动备份，文件写入 /data/backups/。整卷打包可以用：

docker run --rm -v koix-homiary-data:/data -v "$PWD":/out alpine tar czf /out/homiary-backup.tar.gz -C /data .

⁠安全提示

• 容器只提供 HTTP。部署到公网时请在前面用 Nginx、Caddy 或 Traefik 终止 TLS，不要直接把 3000 端口暴露到公网。
• 镜像不含任何预置账号，管理员账号在首次初始化时由你创建，请设置足够强度的密码。
• 修改密码会使其他设备上的会话立即失效（会话签名由密码散列派生）。

⁠项目主页

https://koix.org/products/homiary⁠