StockIndex Server

StockIndex Server 是个人全球证券名称索引服务，统一采集 A股、港股、美股的代码、中文名称、板块与行业分类，提供分页列表与检索 API，便于量化研究与 Agent 助手调用。

基于 Node.js + PostgreSQL，支持 宝塔 PM2、systemd 或 Docker 部署，内置 定时增量同步。

特性

• Node.js 20 + PostgreSQL
• 宝塔 / PM2 / systemd / Docker 多种部署方式
• 内置 cron 定时增量更新（默认每周六 02:00 北京时间）
• 三市场（CN / HK / US）+ 分板块 + A股申万行业 + A股 ETF 名录
• 统一标的 ID：CN:SH.600519 / HK:HK.00700 / US:OQ.AAPL
• Web 检索界面 + /api/v1 REST API

快速开始（宝塔面板，推荐）

服务器已装 Node.js 20+（宝塔「软件商店 → Node 版本管理器」）。

方式 A：宝塔终端一键安装

在宝塔 终端 里执行：

cd /www/wwwroot
git clone git@github.com:Travisun/StockIndexServer.git stock-index-server
cd stock-index-server
cp .env.example .env
# 编辑 .env，设置 SYNC_ADMIN_TOKEN（必填）
nano .env
bash scripts/install-server.sh

脚本会自动：npm ci → build → PM2 启动（需先配置 PostgreSQL）。

PostgreSQL 初始化（宝塔）

# 宝塔安装 PostgreSQL 后执行
DB_PASS=你的数据库密码 bash scripts/setup-pgsql.sh
# 将输出的 DATABASE_URL 写入 .env

方式 B：本地 Mac 一键推送到服务器

本地已有 .env 时：

cp .env.example .env          # 编辑 SYNC_ADMIN_TOKEN
chmod +x scripts/deploy-node.sh
DEPLOY_HOST=你的SSH别名 ./scripts/deploy-node.sh

宝塔必做

1. 安全 → 防火墙：放行 8787（或 .env 里 PORT）
2. 云厂商安全组：同样放行该端口
3. 浏览器访问：http://你的IP:8787/

常用命令

pm2 status stock-index
pm2 logs stock-index
pm2 restart stock-index

首次全量同步

source /opt/stock-index-server/.env   # 或你的项目路径
curl -X POST "http://127.0.0.1:8787/api/v1/admin/sync?mode=full" \
  -H "Authorization: Bearer $SYNC_ADMIN_TOKEN"

快速开始（SSH / CentOS）

服务器需 Node.js 20+。本地准备好 .env 后：

DEPLOY_HOST=你的服务器SSH别名 ./scripts/deploy-node.sh

或在服务器项目目录直接：

bash scripts/install-server.sh

非宝塔环境默认用 systemd；有 PM2 时优先 PM2。

常用环境变量：

变量	说明	默认
DEPLOY_HOST	SSH 主机别名	stock-index
DEPLOY_REMOTE_DIR	远程目录	/opt/stock-index-server
SERVICE_NAME	进程名	stock-index
NPM_REGISTRY	npm 镜像	https://registry.npmmirror.com
USE_PM2	进程管理	auto（宝塔自动 PM2）

服务管理（systemd）：

systemctl status stock-index
systemctl restart stock-index
journalctl -u stock-index -f

快速开始（Docker）

cp .env.example .env          # 编辑 SYNC_ADMIN_TOKEN
docker compose up -d --build

访问 http://localhost:8787/

若 Docker 构建报 Temporary failure resolving 'deb.debian.org'，先是容器 DNS 问题。在服务器上配置后重启 Docker 再构建：

sudo mkdir -p /etc/docker
# 海外可用 1.1.1.1 / 8.8.8.8；国内可改 223.5.5.5 / 119.29.29.29
printf '%s\n' '{' '  "dns": ["1.1.1.1", "8.8.8.8"]' '}' | sudo tee /etc/docker/daemon.json
sudo systemctl restart docker
docker compose up -d --build

国内机器若官方源仍慢/不可用，构建时切镜像：

docker compose build \
  --build-arg APT_MIRROR=mirrors.aliyun.com \
  --build-arg NPM_REGISTRY=https://registry.npmmirror.com
docker compose up -d

首次全量同步：

source .env
curl -X POST "http://localhost:8787/api/v1/admin/sync?mode=full" \
  -H "Authorization: Bearer $SYNC_ADMIN_TOKEN"

同步会在后台自动续跑直至完成，无需多次手动执行。

本地开发

npm install
cp .env.example .env
npm run dev

环境变量

变量	说明	默认
SYNC_ADMIN_TOKEN	管理 API 密钥	必填
PORT	HTTP 端口	8787
DATABASE_URL	PostgreSQL 连接串	必填
CRON_SCHEDULE	定时同步 cron	0 2 * * 6（每周六）
CRON_TZ	时区	Asia/Shanghai
SYNC_BATCH_FETCHES	每批采集页数	20
SYNC_BATCH_PAUSE_MS	批次间暂停（毫秒）	3000
TENCENT_FETCH_DELAY_MS	腾讯 API 请求间隔	800
TENCENT_FETCH_JITTER_MS	请求间隔随机抖动	400
TENCENT_FETCH_MAX_RETRIES	限流/错误重试次数	3
TENCENT_FETCH_RETRY_DELAY_MS	重试退避基数	8000
PUBLIC_HOST	公网访问根 URL（不含端口），首页与 Skill 展示	可选
GITHUB_REPO	首页 GitHub 链接	见 .env.example

采集策略：串行请求 + 请求间隔 + 随机抖动 + 批次间暂停 + 403/429 指数退避重试。全量同步会较慢，但可显著降低 IP 被封风险。若仍遇限流，可调大 TENCENT_FETCH_DELAY_MS 或减小 SYNC_BATCH_FETCHES。

API（/api/v1）

方法	路径	鉴权
GET	/stocks /search /etfs /boards /industries /stats /health	否
POST	/admin/sync?mode=full	Bearer Token

板块

市场	board key	说明
CN	etf	A股 ETF
CN	hsj / cyb / kcb	沪深京 / 创业板 / 科创板
HK	MB / GEM / AH / MBHSCEI / MBHSCCI	主板 / 创业板 / AH 等
US	tec / cdr	科技股 / 中概股

免责声明

数据整理自公开网络，仅供学习与研究，不构成投资建议。

License

MIT