归灯是一个可自建的家人位置共享应用。服务端使用 Rust 编写，位于 server/；Web 客户端使用 React + Vite + TypeScript 编写，位于 client/。客户端只需要填写服务器地址和共享 Token 即可登录，后续可以把 Web 端封装为 Android 或 iOS 应用。
- 使用一个服务器 URL 和一个共享 Token 登录。
- 登录页内置隐私规则和使用许可协议，勾选同意后才能登录。
- 通过浏览器 Geolocation API 获取移动设备位置。
- 支持自定义设备名称。
- 支持中文和英文界面。
- 提供中文/英文管理后台，可查看客户端、删除客户端、清理位置记录，并配置自动清理未更新客户端。
- 支持高德地图。
- 国内地图展示时自动处理坐标偏移：高德使用 GCJ-02，数据库保留原始 GPS 坐标。
- 使用 SQLite 数据库保存数据。
- 记录每个设备最近 7 天的行动轨迹。
- 提供 Dockerfile、Docker Compose 和 Zeabur 部署模板。
- 提供多架构 Docker 镜像构建和推送脚本。
docker compose up -d启动后打开：
http://localhost:3000
本地 Docker 默认服务端地址是：
http://localhost:8080
如果不设置 Token，服务端会在启动时自动生成一个 128 字符随机 Token，并输出到日志中。你也可以手动设置固定 Token：
GUIDENG_TOKEN=replace-with-a-long-random-token docker compose up -d服务端：
cd server
GUIDENG_TOKEN=dev-token cargo run客户端：
cd client
npm install
npm run devApp logo 位于 client/public/assets/guideng-logo.png。在客户端中可通过 /assets/guideng-logo.png 引用，后续封装 Android/iOS 时也可以从该路径取用。
项目提供了 build-and-push.sh，用于构建并推送 guideng-server 和 guideng-client 镜像。脚本会优先使用 Depot；如果本机没有 Depot，则回退到 Docker Buildx。
./build-and-push.sh
TAG=v0.1.0 ./build-and-push.sh
PUSH=0 PLATFORM=linux/amd64 ./build-and-push.sh
IMAGES=server ./build-and-push.sh
IMAGES=client VITE_DEFAULT_SERVER_URL=https://guideng.example.com ./build-and-push.sh常用环境变量：
REPO：镜像仓库命名空间，默认facilisvelox。IMAGE_PREFIX：镜像名前缀，默认guideng。TAG：镜像标签，默认latest。PUSH：是否推送镜像，1表示推送，0表示只构建。BUILDER：构建器，可选auto、depot、buildx。PLATFORM：目标平台，默认linux/amd64,linux/arm64。IMAGES：构建目标，可选all、server、client。VITE_DEFAULT_SERVER_URL：客户端构建时内置的默认服务端地址。
GUIDENG_TOKEN：共享 API Token。不设置或为空时，服务端会自动生成 128 字符随机 Token，并输出到日志中。GUIDENG_ADMIN_PASSWORD：管理后台密码。不设置或为空时，服务端会自动生成并输出到日志中。GUIDENG_ADMIN_PATH：管理后台访问路径，默认/admin。建议部署时改成不容易猜到的路径，例如/admin-your-random-path。GUIDENG_BIND：监听地址，默认0.0.0.0:8080。GUIDENG_DATABASE_URL：SQLite 数据库文件路径，默认/data/guideng.sqlite3。GUIDENG_LOG_PATH：日志文件路径。默认写入项目server/guideng.log；Docker Compose 中默认写入/data/guideng.log。GUIDENG_CORS_ORIGINS：允许跨域访问的来源，多个来源用英文逗号分隔，默认*。GUIDENG_AMAP_WEB_JS_API_KEY：高德 Web 端 JavaScript API Key。GUIDENG_AMAP_WEB_JS_SECURITY_CODE：高德 Web 端 JavaScript API 安全密钥。GUIDENG_AMAP_ANDROID_KEY：高德 Android SDK Key，供以后 Android App 使用。GUIDENG_AMAP_IOS_KEY：高德 iOS SDK Key，供以后 iOS App 使用。
所有 /api/* 接口都需要携带 Token，可以使用下面任意一种方式：
Authorization: Bearer <token>
X-Guideng-Token: <token>接口列表：
GET /health：健康检查。GET /api/config：获取地图供应商和高德 Key 配置。GET /api/devices：获取设备列表和每个设备的最新位置。POST /api/devices：注册或更新当前设备。PATCH /api/devices/:id：修改设备名称或平台信息。POST /api/devices/:id/location：上报设备位置。GET /api/devices/:id/tracks?days=7：获取设备最近轨迹，最多 7 天。
服务端会保存每次位置上报，并保留最近 7 天的轨迹点。写入新位置时，会自动清理超过 7 天的旧轨迹。
服务端内置管理后台，默认路径为：
http://localhost:8080/admin
如果设置了 GUIDENG_ADMIN_PATH，请使用对应路径访问。管理密码来自 GUIDENG_ADMIN_PASSWORD；如果没有手动设置，服务端会在启动时自动生成并写入日志。
管理后台支持中文和英文，可点击页面右上角的 English / 中文 按钮切换，也可以在地址后追加 ?lang=zh 或 ?lang=en。
管理后台可以：
- 查看已注册客户端及其最后位置。
- 删除单个客户端的位置记录。
- 删除单个客户端。
- 手动清理超过指定天数未更新位置的客户端。
- 设置自动清理天数；留空保存可关闭自动清理。
推荐使用 HTTPS 部署。移动端浏览器在非 localhost 环境下通常要求 HTTPS 才能使用高精度定位，否则客户端可能无法获取位置权限。
详细本地部署流程见：归灯本地部署指南 / English deployment guide。
使用 Docker Compose：
GUIDENG_TOKEN=replace-with-a-long-random-token docker compose up -d默认会拉取 facilisvelox/guideng-server:latest 和 facilisvelox/guideng-client:latest。如需使用自定义镜像：
GUIDENG_SERVER_IMAGE=yourname/guideng-server:v0.1.0 \
GUIDENG_CLIENT_IMAGE=yourname/guideng-client:v0.1.0 \
docker compose up -d项目也包含 zeabur.yaml，可以作为 Zeabur 部署模板使用。部署时可以手动设置 GUIDENG_TOKEN；如果留空，服务端会自动生成并写入日志。
项目根目录提供了 nginx.conf，用于本地先通过 Docker Compose 启动服务端，再用宿主机 Nginx 反代服务端端口。
docker compose up -d
sudo cp nginx.conf /etc/nginx/nginx.conf
sudo nginx -t
sudo systemctl reload nginx默认反代目标是：
127.0.0.1:8080
配置中默认反代：
/health/api/GUIDENG_ADMIN_PATH对应的后台路径，例如/admin或你自定义的随机路径。
归灯默认使用 SQLite。Docker 部署时数据库位于容器内 /data/guideng.sqlite3，并通过 Compose volume 持久化。
如果你要备份数据，备份 /data 对应的 volume 或 SQLite 文件即可。
- 这个项目使用一个共享 Token，适合家庭或小范围自建使用。
- 如果没有手动设置
GUIDENG_TOKEN，请从服务端日志中复制启动时生成的 Token。 - 如果客户端和服务端部署在不同域名下，请根据实际域名设置
GUIDENG_CORS_ORIGINS。 - 地图服务由各地图供应商提供，部分供应商可能在不同地区有访问限制或坐标系差异。
如果这个项目对你有用的话，请我喝罐可乐吧。
MIT