StartDeck 是一套面向 NAS、家庭服务器与个人工作流的自托管浏览器起始页。它将站点入口、组件化信息面板、系统状态、Docker 管理、智能图标识别和网络访问策略整合为一个可长期运行、可迁移、可备份的个人工作台。

StartDeck 不是简单的书签页，而是面向自托管场景的浏览器工作台。它适用于需要集中管理内网服务、公网入口、开发工具、个人日程、轻量运维信息和常用 API 服务的用户。

核心目标：

• 统一入口：集中管理站点、分组、搜索引擎、内网地址与公网地址。
• 自托管数据：布局、书签、组件配置、上传资源和运行缓存保存在用户自己的服务器中。
• 组件化桌面：通过网格布局组合天气、日历、待办、备忘录、番茄时钟、Docker、系统状态、AI 使用量、TAPD 缺陷等组件。
• 智能元数据：自动识别站点标题、描述和图标，并通过独立元数据服务维护内置图标库与运行期缓存。
• 运维友好：提供系统状态、Docker 容器状态、IP 与网络信息、版本检查等自托管常用能力。
• 可扩展：支持自定义 HTML/CSS/JS 组件、iframe 组件、全局自定义 CSS 和运行时脚本。

天气组件	待办组件	AI 使用量	TAPD 缺陷

StartDeck 由 Vue 前端、Rust 主服务和 Rust 元数据服务组成。Docker 镜像会同时启动主服务和元数据服务，生产环境通常只需要对外暴露主服务端口。

Browser
  |
  | HTTP / WebSocket
  v
Vue 3 Frontend
  |
  | /api, static assets
  v
Rust startdeck-server
  |
  | SQLite, runtime files, Docker socket, icon API
  v
Rust startdeck-metaserver

• Frontend：Vue 3、TypeScript、Pinia、GridStack，负责首页、设置、组件运行态和交互。
• Backend：Rust + Axum，提供认证、配置持久化、站点元数据、代理、Docker、系统状态、天气/IP 等接口。
• MetaServer：独立 Rust 服务，负责站点元数据识别、图标库和图标缓存。
• Storage：SQLite 保存配置和运行数据，Data/ 保存上传资源、背景图和元数据服务缓存。

生产环境推荐直接使用 Docker Hub 镜像 apkdv/startdeck:latest。不建议在生产服务器上通过源码构建部署；源码构建更适合本地开发、镜像发布和问题排查。

当前 Docker Hub 发布工作流面向 linux/amd64 架构。ARM 服务器或其他架构需要确认运行环境是否支持该镜像，或自行发布对应架构镜像。

1. 准备目录和环境变量：

mkdir -p /opt/startdeck
cd /opt/startdeck

cat > .env <<'EOF'
STARTDECK_ADMIN_PASSWORD=change-me
EOF

默认情况下，会话签名密钥会在挂载的 Data/data/secrets/session-signing.key 中自动生成并复用。只有在需要通过环境变量集中管理密钥时，才设置 STARTDECK_SECRET，且必须使用 openssl rand -base64 32 生成。

2. 创建 compose.yml：

services:
  startdeck:
    image: apkdv/startdeck:latest
    container_name: startdeck
    restart: unless-stopped
    ports:
      - "9001:9001"
    env_file:
      - .env
    environment:
      PORT: "9001"
      HOST: "0.0.0.0"
      META_SERVER_PORT: "9002"
      META_SERVER_DATA_DIR: /app/Data/meta-service
      META_SERVER_RESOURCE_DIR: /app/meta-service-defaults/data
      META_SERVER_BASE_URL: http://127.0.0.1:9002
      META_SERVER_TIMEOUT_MS: "60000"
      QWEATHER_API_HOST: "${QWEATHER_API_HOST:-}"
      QWEATHER_PROJECT_ID: "${QWEATHER_PROJECT_ID:-}"
      QWEATHER_CREDENTIAL_ID: "${QWEATHER_CREDENTIAL_ID:-}"
      QWEATHER_PRIVATE_KEY_FILE: "${QWEATHER_PRIVATE_KEY_FILE:-}"
      TENCENT_MAP_API_HOST: "${TENCENT_MAP_API_HOST:-}"
      TENCENT_MAP_KEY: "${TENCENT_MAP_KEY:-}"
    volumes:
      - ./Data:/app/Data
      - /var/run/docker.sock:/var/run/docker.sock

如不使用 Docker 管理组件，请删除 /var/run/docker.sock 挂载。该挂载权限较高，仅应在可信服务器上启用。

3. 拉取并启动：

docker compose pull
docker compose up -d
docker compose logs -f startdeck

访问地址：

http://<server-ip>:9001

默认管理员用户名为 admin。生产环境必须设置 STARTDECK_ADMIN_PASSWORD，并在首次登录后修改为长期使用的强密码。

适合临时验证或单机快速部署：

docker run -d \
  --name startdeck \
  --restart unless-stopped \
  -p 9001:9001 \
  -v "$PWD/Data:/app/Data" \
  -e PORT=9001 \
  -e HOST=0.0.0.0 \
  -e STARTDECK_ADMIN_PASSWORD=change-me \
  -e META_SERVER_PORT=9002 \
  -e META_SERVER_DATA_DIR=/app/Data/meta-service \
  -e META_SERVER_RESOURCE_DIR=/app/meta-service-defaults/data \
  -e META_SERVER_BASE_URL=http://127.0.0.1:9002 \
  -e META_SERVER_TIMEOUT_MS=60000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  apkdv/startdeck:latest

升级前建议备份 Data 目录：

cd /opt/startdeck
docker compose down
tar -czf "startdeck-data-$(date +%F).tar.gz" Data
docker compose pull
docker compose up -d

升级后可检查主服务和元数据服务：

curl -fsS http://127.0.0.1:9001/healthz
docker compose logs --tail=100 startdeck

默认运行数据集中挂载在 Data/：

Data/data/startdeck.sqlite3        # 布局、书签、组件配置、用户与系统配置
Data/data/users/                   # 用户配置数据
Data/PC/                           # 桌面端背景图
Data/APP/                          # 移动端背景图
Data/meta-service/                 # 元数据服务运行期缓存和数据

迁移到新服务器时，停止旧容器后复制整个 Data 目录，并在新服务器使用相同挂载路径启动。

反向代理需要转发 HTTP 与 WebSocket：

• 应用入口：/
• API：/api/*
• WebSocket：/ws
• 图标与缓存：/icons/*、/cache/*、/icon-cache/*
• 背景图：/backgrounds/*、/mobile_backgrounds/*
• 代理接口：/proxy

子路径部署建议将完整路径转发到同一个容器端口，并保留 WebSocket Upgrade 头。前端默认使用相对资源路径，可适配常见子路径反代；如需要固定构建路径，请在构建阶段设置 VITE_APP_BASE_PATH。

Nginx 反向代理示例需包含 WebSocket Upgrade 头：

location /ws {
    proxy_pass http://127.0.0.1:9001/ws;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

QWeather 需要同时配置 Host、项目 ID、凭证 ID 和私钥文件才会启用。私钥建议通过只读 volume 或 Docker secret 挂载，不要写入镜像或仓库。

仓库中仍保留 deploy_debian.sh 和 manage.sh，用于需要 systemd + Nginx 的自管理部署。但生产推荐路径已经调整为 Docker Hub 镜像部署。除非明确需要二进制包和 systemd 方式，否则不要优先使用源码或 Release 包脚本部署。

• Node.js ^20.19.0 或 >=22.12.0
• Rust 1.94
• npm

cd frontend
npm ci
npm run start:hot

也可以分开启动：

# 终端 1：元数据服务
npm --prefix frontend run meta-server

# 终端 2：主服务
npm --prefix frontend run server:hot

# 终端 3：前端开发服务器
npm --prefix frontend run dev

默认端口：

# 前端
cd frontend
npm run build
npm test
npm run test:e2e
npm run lint

# 后端
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo run --bin startdeck-server
cargo run --bin startdeck-metaserver

根目录的 docker-compose.yml 面向本地构建和容器路径验证，默认构建 startdeck:local：

docker compose up --build

Docker 构建默认使用国内可访问性更好的 Node 与 Rust 镜像源：

如需切回官方源或使用企业内网源，可通过环境变量覆盖：

NPM_CONFIG_REGISTRY=https://registry.npmjs.org \
STARTDECK_CRATES_IO_INDEX=sparse+https://index.crates.io/ \
docker compose build

这些参数只影响容器构建过程中的 Node/Rust 依赖下载；基础镜像 node:*、rust:*、debian:*、busybox:* 的拉取仍由 Docker daemon 的 registry mirror 配置控制。

frontend/                                  # Vue 3 frontend
  src/components/                          # UI components
  src/features/                            # Runtime widgets and feature modules
  src/stores/                              # Pinia stores
  public/                                  # Source static assets
rust/crates/startdeck-server/              # Main Rust backend
rust/crates/startdeck-metaserver/          # Site metadata service
rust/crates/startdeck-core/                # Shared SQLite/domain code
Data/                                      # Runtime data and generated public assets
debian/                                    # Debian/Ubuntu packaging and service files
Dockerfile
docker-compose.yml

cd frontend
npm run build
npm test

cd ..
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
docker compose up --build

涉及页面、组件、拖拽、移动端布局或浏览器交互的改动，应额外执行 Playwright 或浏览器验收。

官网源文件是 frontend/public/intro.html，GitHub Pages workflow 是 .github/workflows/deploy-pages.yml。

推送到 main 后，workflow 会把官网页发布到 https://appdev.github.io/StartDeck/，并保留 /intro.html 入口。首次启用时需要在 GitHub 仓库 Settings -> Pages 中选择 GitHub Actions 作为发布来源。

• GitHub: https://github.com/appdev/StartDeck
• Docker Hub: https://hub.docker.com/r/apkdv/startdeck
• 官网: https://appdev.github.io/StartDeck/

StartDeck is released under the GNU AGPLv3.