DSA DOCS

DSA 文档中心

围绕 DSA 真实使用路径：快速开始、Actions、本地、Docker，以及源项目完整文档。

GitHub Actions 部署 本地运行 Docker 部署 打开 DSA 仓库
部署与打包

桌面端打包说明 (Electron + React UI)

本项目可打包为桌面应用，使用 Electron 作为桌面壳，apps/dsa-web 的 React UI 作为界面。

源文档 版本: v3.26.1-2-g487e49e 更新: 2026-07-16
DESKTOP
在 GitHub 查看源文档

本项目可打包为桌面应用，使用 Electron 作为桌面壳，apps/dsa-web 的 React UI 作为界面。

架构说明

本地开发

一键启动（开发模式）：

powershell -ExecutionPolicy Bypass -File scripts\run-desktop.ps1

或手动执行：

  1. 构建 React UI（输出到 static/）
cd apps/dsa-web
npm install
npm run build
  1. 启动 Electron 应用（自动拉起后端）
cd apps/dsa-desktop
npm install
npm run dev

首次运行时会自动从 .env.example 复制生成 .env。

打包 (Windows)

前置条件

一键打包

powershell -ExecutionPolicy Bypass -File scripts\build-all.ps1

该脚本会依次执行：

  1. 构建 React UI
  2. 安装 Python 依赖
  3. PyInstaller 打包后端
  4. electron-builder 打包桌面应用

当前 Windows 安装包使用 NSIS 向导式安装流程，仅支持当前用户安装且已禁用管理员提权，安装时可手动选择目标目录（例如非 C 盘）。安装器通过 NSIS .onVerifyInstDir 回调在安装器层面阻止选择 Program Files、Windows 等系统保护目录——选择这些路径时"下一步"按钮会被自动禁用。安装完成后，桌面端仍会按现有逻辑在安装目录旁生成/读取 .env、data/stock_analysis.db（含 data/stock_analysis.db-wal / data/stock_analysis.db-shm）和 logs/desktop.log。推荐使用默认的 per-user 安装目录。如果不想安装，仍可继续分发 win-unpacked 免安装包。

GitHub CI 自动打包并发布 Release

仓库已支持通过 GitHub Actions 自动构建桌面端并上传到 GitHub Releases：

macOS 提示“应用已损坏，无法打开”

当前 macOS DMG 尚未使用 Apple Developer 证书签名和公证。通过浏览器下载后，macOS Gatekeeper 可能因此提示“Daily Stock Analysis 已损坏，无法打开”或“无法验证开发者”；这通常是系统对未签名、未公证应用的拦截，不代表 DMG 文件必然损坏。

请按以下顺序排查：

  1. 只从项目的 GitHub Releases 下载附件，并确认安装包架构与 Mac 一致：Apple 芯片（M1/M2/M3/M4 等）使用 daily-stock-analysis-macos-arm64-.dmg，Intel 芯片使用 daily-stock-analysis-macos-x64-.dmg。不要对第三方转载或来源不明的安装包绕过 Gatekeeper。
  2. 打开 DMG，将 Daily Stock Analysis 拖入“应用程序”后尝试启动一次。若被拦截，进入“系统设置 -> 隐私与安全性”，在安全性提示处确认应用名称，然后点击“仍要打开”，按系统提示再次确认。较旧 macOS 的对应入口为“系统偏好设置 -> 安全性与隐私 -> 通用”。
  3. 仅当安装包确认来自上述官方 Release、且“仍要打开”仍无法放行时，打开“终端”清除该应用的下载隔离属性，然后重新启动：
xattr -dr com.apple.quarantine "/Applications/Daily Stock Analysis.app"

如果应用不在 /Applications，请将命令中的路径替换为实际 .app 路径。不要对整个“应用程序”目录执行 xattr，也不要对来源不明的应用执行此命令。长期彻底消除该提示需要在发布流程中接入 Apple Developer 签名与 notarization（公证），不属于上述临时放行步骤。

建议发布流程：

  1. 合并代码到 main
  2. 由自动打 tag 工作流生成版本（或手动创建 tag）
  3. desktop-release 工作流自动构建并把两个平台安装包附加到对应 GitHub Release

发版前可复现验证（桌面更新链路）

桌面端自动更新链路依赖 Windows NSIS 安装产物、latest.yml 与 *.blockmap 元数据。当前桌面 CI 不覆盖 desktop-release 打包产物可发布链路，提交前建议补充如下本地验证：

说明：该清单专注于 Windows NSIS 安装版与 electron-updater 发布元数据。当前 Linux 环境无法直接产出 Windows 安装包和 updater 元数据（latest.yml / *.blockmap），此类链路需在 Windows 发布执行器或 Windows 本机环境复核。

若在非 Windows 环境无法完成上述验证，请在 PR 验收说明中明确补齐 Windows 发布链路复核人、复核时间窗及 desktop-release 产物检查结果（release/tag 与 daily-stock-analysis-windows-installer-<tag>.exe、latest.yml、*.blockmap 版本一致性与可下载性）。

  1. 先构建 Web 静态产物（桌面端主窗口与设置页入口依赖）
cd apps/dsa-web
npm ci
npm run lint
npm run build
  1. 回到桌面端，补齐依赖、运行 preload 单测、再执行 Electron 打包
cd ../dsa-desktop
npm ci
npm test
npm run build

在 Windows 发布复核环境，还可额外执行：

./scripts/verify-desktop-updater-artifacts.ps1 -ReleaseTag v$(node -p "require('./apps/dsa-desktop/package.json').version")
预期当前执行环境不支持生成 Windows NSIS 安装器时，请在交付说明中明确注明平台限制，并要求指定的 Windows 发布链路复核人补齐该项验证。
  1. 检查更新元数据是否产出
ls -1 dist | sort
ls -1 dist/*.yml dist/*.blockmap 2>/dev/null || true
  1. 强制对齐版本与发布附件（可在 Windows 环境或能产出 NSIS 产物的执行器上复核）
RELEASE_TAG="v$(node -p \"require('./package.json').version\")"
REPO="ZhuLinsen/daily_stock_analysis"

for f in dist/*latest.yml dist/*.blockmap dist/daily-stock-analysis-windows-installer-*.exe; do
  [ -f \"$f\" ] && echo \"[FOUND] $f\"
done

if [ -f dist/latest.yml ]; then
  echo \"---- latest.yml 版本片段 ----\"
  grep -E \"^version:|^files:|^sha512:\" dist/latest.yml
fi

echo \"---- Release 清单（人工核对）----\"
echo \"Release Tag: $RELEASE_TAG\"
echo \"Release 地址: https://github.com/$REPO/releases/tag/$RELEASE_TAG\"
echo \"应核对附件是否包含:\"
echo \"- daily-stock-analysis-windows-installer-*.exe\"
echo \"- latest.yml\"
echo \"- *.blockmap\"
echo \"并确保 latest.yml 中 version 与 tag 的语义化版本一致，path/url 与安装包附件名一致\"

5a. 建议在 PR 描述里记录的“可复核输出”（Windows）：

echo "release-tag=${RELEASE_TAG}"
echo "latest.yml version:"
grep -E "^version:" dist/latest.yml
echo "latest.yml files:"
sed -n '1,80p' dist/latest.yml
echo "packaging artifacts:"
ls -1 dist/*.yml dist/*.blockmap dist/*installer*.exe 2>/dev/null | sort

Windows 发布链路复核清单（在 PR 后由发布团队/维护者执行）：

  1. Windows/NSIS 产物与发布附件一致性请在 Windows 环境手动验证（可人工触发发布流程），并在升级后核对运行时文件留存：
  1. 安装前后分别记录安装目录中的 .env、data/stock_analysis.db、data/stock_analysis.db-wal、data/stock_analysis.db-shm、logs/desktop.log 的 SHA256；
  2. 确认桌面端下一次启动后，上述文件仍存在且与安装前记录一致；
  3. 如不一致，可在应用退出后检查用户数据目录中的 .dsa-desktop-update-backup 是否清理完整，并结合最新日志串联排查。

Windows 平台建议使用 PowerShell 执行：

Get-FileHash .env,data\\stock_analysis.db,data\\stock_analysis.db-wal,data\\stock_analysis.db-shm,logs\\desktop.log -Algorithm SHA256

说明：应用已在 Windows NSIS 安装版的“重启安装”前停止内置后端、备份安装目录旁上述运行时文件，并以静默模式运行更新安装器，目的是避免安装向导抢先覆盖仍在运行的桌面端进程，同时降低更新过程中文件丢失风险；若恢复失败，桌面端会显示更新安装错误并保留手动下载路径供回退处理。此次修复仅改动 Windows 更新安装链路与内置后端进程生命周期处理，不涉及设置保存语义、模型运行时清理策略或配置迁移行为。

分步打包

  1. 构建 React UI
cd apps/dsa-web
npm install
npm run build
  1. 按现有脚本打包 Python 后端（脚本已内置 AlphaSift 与 AkShare 数据文件收集）
powershell -ExecutionPolicy Bypass -File scripts\build-backend.ps1
bash scripts/build-backend-macos.sh

该脚本会在安装依赖后执行 --collect-all alphasift 和 --collect-data akshare。构建完成后会校验 alphasift.dsa_adapter 可导入，并确认 AkShare 的 file_fold/calendar.json 已进入冻结产物，避免发行包在热点题材或日线增强路径中因缺少 package data 降级。

  1. 打包 Electron 桌面应用
cd apps/dsa-desktop
npm install
npm run build

打包产物位于 apps/dsa-desktop/dist/。Windows 安装器会生成 daily-stock-analysis-windows-installer-<tag>.exe，安装向导中可选择安装目录。

目录结构

Windows 安装包模式下，安装器仅支持当前用户安装且已禁用管理员提权，用户可在安装向导中选择安装目录；安装器会在安装器层面阻止选择 Program Files、Windows 等系统保护目录（选择时"下一步"按钮自动禁用），安装完成后，应用会在安装目录旁生成/读取 .env、data/stock_analysis.db（含 data/stock_analysis.db-wal / data/stock_analysis.db-shm）和 logs/desktop.log。请保留默认的 per-user 安装位置或选择其他用户可写目录。

win-unpacked 免安装模式下，目录结构如下：

win-unpacked/
  Daily Stock Analysis.exe    <- 双击启动
  .env                        <- 用户配置文件（首次启动自动生成）
  data/
    stock_analysis.db         <- 数据库主文件
    stock_analysis.db-wal     <- WAL 日志文件（更新备份/恢复）
    stock_analysis.db-shm     <- WAL 共享元文件（更新备份/恢复）
  logs/
    desktop.log               <- 运行日志
  resources/
    .env.example              <- 配置模板
    backend/
      stock_analysis.exe      <- 后端服务

配置文件说明

配置备份 / 恢复 .env

建议：从旧版本升级的 macOS 用户仍可在升级前执行一次 导出 .env 作为保险；如果旧 .app 已经被整体替换，包内旧文件无法凭空恢复，只能通过备份导入。

设置页版本信息

局域网访问 Windows 桌面端 WebUI

桌面端更新提醒

常见问题

启动后一直显示 "Preparing backend..."

  1. 检查 logs/desktop.log 查看错误信息
  2. 确认 .env 文件存在且配置正确
  3. 确认端口 8000-8100 未被占用；桌面端会自动选择其中一个可用端口，无需通过 .env 手动改 WEBUI_PORT
  4. 如果日志里显示 Electron 等待的端口和后端实际监听端口不一致，优先升级到包含桌面端端口同步修复的版本

后端启动报 ModuleNotFoundError

PyInstaller 打包时缺少模块，需要在 Windows 与 macOS 后端构建脚本中同步增加 --hidden-import，并对冻结产物执行运行时导入校验。当前脚本会显式安装、冻结并探测 LiteLLM 运行路径需要的 orjson；若日志包含 No module named 'orjson'，请升级到修复版本并重新构建，不能只在已发布目录中手工安装依赖。

如果日志提示缺少 akshare/file_fold/calendar.json，说明后端冻结产物没有完整收集 AkShare package data。请使用仓库当前的 scripts/build-backend.ps1 或 scripts/build-backend-macos.sh 重新构建；脚本会在生成桌面包前检查该文件，缺失时直接终止构建。

UI 加载空白

确认 static/index.html 存在，如不存在需重新构建 React UI。

macOS 升级后配置迁移

旧版本曾把运行时 .env、数据库和日志写在 .app 包内部。新版本改为使用 Electron 用户数据目录，并在旧 .app 包内文件仍可访问时做一次性迁移。迁移规则是“目标不存在才复制”，避免覆盖用户已经在新版本中保存的配置。

如果旧 .app 已经被整体替换，旧包内 .env 无法由新版本自动恢复。此时可使用升级前导出的 .env 在 系统设置 -> 配置备份 中手动导入；完成一次迁移或重新配置后，后续版本会继续复用用户数据目录，不再随 .app 替换丢失。

分发给用户

Windows 分发现在有两种方式：

  1. 安装包：分发 apps/dsa-desktop/dist/ 下的 daily-stock-analysis-windows-installer-.exe，用户安装时可自行选择目标目录
  2. 免安装包：将 apps/dsa-desktop/dist/win-unpacked/ 整个文件夹打包发给用户

使用 win-unpacked 免安装包时，用户只需：

  1. 解压文件夹
  2. 编辑 .env 配置 API Key 和股票列表
  3. 双击 Daily Stock Analysis.exe 启动