优雅草 · 公信查（Youyacao· Public Trust Check）v1.0.3更新增加体 - 文章 - 开发者社区

优雅草 · 公信查（Youyacao· Public Trust Check）v1.0.3更新增加体制人员结构参考编外招聘参考省考信息参考国企招聘参考

优雅草 · 公信查（Youyacao· Public Trust Check）

产品概要：公信查是优雅草科技、创始人卓伊凡发起的非官方、民间参考工具，聚焦两类需求：（1）防范冒充公职人员等诈骗——对公开人事线索做泛检索与结构化归纳；（2）招考与编制结构公开信息参考——在合规前提下，由大模型按地区与关键词输出可复核的检索路径与口径说明（不替代统计年鉴与组织人事台账）。**当前版本（v1.0.3）**在首页提供 五大功能入口（公职人员线索 + 四类招考/结构参考），长耗时查询配套 流式保活 与 等待秒数 提示。交付形态为 PC Web 与 UniApp（H5 / 微信小程序等可扩展 App）。

技术栈：UniApp（小程序 / H5 / App）+ 独立 PC 端（Vue 3 + Vite）+ Node 后台（Hono）+ DeepSeek 大模型 JSON 结构化输出。

版本与发布：首发口径为 2026 年 5 月 6 日；当前仓库与线上页脚展示版本为 v1.0.3（见 PRODUCT_VERSION、PRODUCT_EDITION_LINE，apps/pc-web 与 apps/mobile 的 constants/brand.ts）。若对外文案需区分「首发日」与「迭代日」，可在 PRODUCT_EDITION_LINE 中自行改写日期表述。

访问统计（51.la） ：已在 PC 端（apps/pc-web/index.html）与 UniApp H5 入口页（apps/mobile/index.html）嵌入 51.la 统计脚本；浏览器访问 PC 站点或移动端 H5 时会加载 SDK 并初始化。微信小程序、App 等非标准 H5 宿主若需统计，需按各平台文档另行对接。

更新日志

按时间倒序记录主要迭代；细粒度提交以 Git 历史为准。

2026-05-07 · v1.0.3（功能扩展与界面改版）

类别	内容
产品形态	首页统一为功能中心：五入口并列——① 公职人员公开线索（原公信查主流程）；② 体制人员结构参考；③ 编外招考参考；④ 省考信息参考；⑤ 国企招聘参考。②～⑤ 走同一后端 `POST /api/v1/hr/public-insight`，由 `hrInsightPrompt.ts` 约束 JSON 输出形态。
PC 端	`FeatureHub.vue` 五卡片入口；`HrInsightView.vue` 承载招考四类表单与报告；`App.vue` 内通过 `surface`（`hub` / `official` / `hr`）切换。公职人员两阶段查询、NDJSON 流式保活、响应解析与等待耗时大号秒表展示已统一风格。
移动端	`pages/index` 功能中心；`pages/official` 表单 + `pages/result` 结果；`pages/hr-insight` 招考参考。公职人员结果页 `uni.request` 已与 PC 对齐：长超时、`X-GXC-Stream: 1`、`dataType: 'text'`，并复用 `parseQueryResponseBody` 解析 NDJSON/整段 JSON。招考页在查询中展示实时秒表。
健壮性	`parseQueryResponseBody`（PC / 移动）增强：非 JSON、502、HTML 误判、404 纯文本等场景给出更可读提示（含「需部署含 `hr/public-insight` 的 API」等运维向说明）。API 层 `204 No Content` 等响应与 TypeScript 构建兼容性已修正。
界面与体验	全站视觉调整为政务向庄重风格：中国红主色（绛红系）+ 金色点缀 + 暖白底；顶栏/品牌区、按钮、卡片、页脚与加载中倒计时高对比展示，便于用户感知「仍在处理、勿中断」。
版本号	`PRODUCT_VERSION`、各端 `package.json`、`manifest.versionName` / `versionCode` 等与 v1.0.3 对齐；本文档功能架构章节标题同步。

2026-05-06 · v1.0.0（首发基线）

公职人员 两阶段 查询（泛检索材料 → 点选候选人 → 公职人员判定参考）、合规横幅与免责声明、PC + UniApp（H5）交付、DeepSeek 结构化输出、gxc-api（Hono）与 Nginx 长超时 / 流式保活说明等。详见下文「软件开发背景」「产品功能架构」与部署章节。

一、软件开发背景与社会价值

社会上以「冒充公职人员」「虚构内部关系」实施电信诈骗、婚恋与商业欺诈的案件时有发生，群众在信息不对称下容易轻信对方口头「身份」。优雅草 · 公信查由优雅草科技发起，承载创始人卓伊凡「技术向善、为国为民」的初心：我们刻意不做「全面核验在编公职人员」的民间权威，而是将产品明确定位为非官方、仅供反诈与公众参考的公开信息整合工具——在合法合规前提下，对政府网站、官方媒体公示等已主动公开的人事线索做摘录与结构化呈现，帮助用户在面对「自称领导、自称在编」等话术时多一道理性防线。

本软件不采集身份证号、手机号、住址等敏感个人信息，不对接任何内部组织人事或政务内网，不收录依法未公开的涉密岗位、军转、内部定向招录等信息；展示内容不全面、不实时，不具备任何身份核验的法律效力。精准认定与办事结论请务必通过人社、组织部门、用人单位等对外公开的官方渠道核实；遇可疑资金或隐私操作要求，请及时向公安机关与反诈平台求助。

第二章所列招考与编制结构参考（编外、省考、国企等）与公职人员查询共用同一 gxc-api 与合规红线：输出为公开信息层面的归纳与检索提示，不替代人事考试机构、用人单位或统计年鉴的权威数据。

在线访问地址

端	软件地址
PC 版本	https://gxcpc.youyacao.com
移动端（H5）	https://gxch5.youyacao.com

界面截图

picture.image

二、产品功能架构（v1.0.3）

本章描述当前版本用户能做什么、数据从哪来、与官方系统的关系；二次开发请结合 §2.3 源码索引 跳转具体文件。

2.1 总体交互

端	首页 / 入口	说明
PC	`FeatureHub`（`apps/pc-web/src/components/FeatureHub.vue`）+ 顶栏合规横幅	五张功能卡片；公职人员查询仍在 `App.vue` 内通过 `surface` 切换（`hub` → `official` / `hr`）。
移动端	`pages/index/index`	五张功能卡片；公职人员表单在 `pages/official/official`，结果在 `pages/result/result`；四类招考在 `pages/hr-insight/hr-insight?kind=…`（见 `pages.json`）。

首页以简介 + 合规 + 入口为主；反腐快报、星光榜、编制量级说明等仍集中在公职人员查询流程页（PC 为 official 同屏内容；移动为 official 页）。

典型用户路径（简述） ：

打开功能中心 → 选择 公职人员线索 或某一类 招考 / 结构参考。
公职人员：填写姓名与关联地区（必填）→ 一阶段展示材料与候选人 → 必要时点选一条 → 二阶段查看参考归纳（百分比、落马标识等均为公开信息层面的模型归纳，非编制认定）。
招考 / 结构：填写地区及表单要求的其它字段 → 等待报告（界面展示已等待秒数，长请求建议勿锁屏/勿杀进程）→ 阅读章节化报告与检索建议，重要事项仍须以政府官网与人事考试网为准。

2.2 五大功能一览

#	功能	用户输入	后端接口	数据性质与边界
①	公信查 · 公职人员公开线索	姓名、关联地区（必填，市/县/乡镇或工作地等自由文本）、单位关键词（选填）	`POST /api/v1/query/deepseek-summary`（`stage`: `research` / `judgment` / `full`）	非组织人事认定；两阶段：先材料与候选人，点选后再判定参考结论；须配合官方渠道核实。
②	体制人员结构参考	地区（市/县/乡镇，必填）	`POST /api/v1/hr/public-insight`，`kind=establishment_snapshot`	行政编、事业编、编外等为公开政策与常识层面的归纳，非编办实时台账。
③	编外与机关辅助招考参考	地区必填、专业选填	`kind=contract_recruitment`	侧重当年机关及政法系统编外、购买服务等线索；人事考试网 URL 不得虚构，无把握时给检索提示。
④	省考信息参考	地区必填	`kind=provincial_exam`	当年省考职位与公告路径归纳，以省级人事考试网为准。
⑤	国企招聘参考	地区必填、国企类型关键词必填（如烟草、航空）	`kind=soe_recruitment`	公开招聘线索归纳，不替代央企/省属国企官方招聘系统。

以上 ②～⑤ 均由 hrInsightPrompt.ts 约束 JSON 形态（章节、统计行、招考条目、链接占位等），与公职人员 queryPrompt.ts 分离维护。

接口与前端约定（运维须知） ：

公职人员与招考类长耗时接口均支持请求头 X-GXC-Stream: 1，响应为 application/x-ndjson 心跳流，减轻网关空闲断连（详见 §九与 §十二、常见问题）。
生产环境 Nginx 反代 API 时建议 proxy_buffering off、足够的 proxy_read_timeout，与仓库内 PC / 移动前端超时配置一致。

2.3 关键源码索引（二次开发）

说明	路径
PC 功能中心	`apps/pc-web/src/components/FeatureHub.vue`
PC 招考四类表单与结果展示	`apps/pc-web/src/components/HrInsightView.vue`、`apps/pc-web/src/lib/postHrPublicInsight.ts`
PC 公职人员主流程与布局	`apps/pc-web/src/App.vue`（`surface`: `hub`
PC NDJSON 解析（与流式保活配合）	`apps/pc-web/src/lib/parseQueryResponseBody.ts`、`postDeepseekSummary.ts`
移动功能中心	`apps/mobile/src/pages/index/index.vue`
移动公职人员表单 / 结果	`apps/mobile/src/pages/official/official.vue`、`apps/mobile/src/pages/result/result.vue`
移动招考请求	`apps/mobile/src/lib/postHrPublicInsight.ts`、`parseQueryResponseBody.ts`
移动招考页	`apps/mobile/src/pages/hr-insight/hr-insight.vue`
API 路由与流式封装	`apps/api/src/index.ts`
公职人员 Prompt	`apps/api/src/queryPrompt.ts`
招考类 Prompt	`apps/api/src/hrInsightPrompt.ts`

2.4 其它界面能力

反腐快报 / 星光榜：展示类（公职人员流程页内；数据见 apps/*/src/data/mock-feeds 等）。
合规：页眉横幅 HEADER_LEGAL_NOTICE_*、查询条 SOURCE_QUERY_DISCLAIMER、首次免责声明弹窗。
品牌理念（界面已展示） ：优雅草科技，秉行「侠之大者，为国为民」。
加载反馈：公职人员一阶段 / 二阶段与招考参考查询中，PC 与移动端均展示实时等待秒数（高对比样式），便于用户判断请求仍在进行。
视觉规范（v1.0.3） ：全站以绛红 + 金色点缀 + 浅暖底为主色，强化政务参考类产品的可读性与正式感；具体色值见各端 Vue 文件内样式（未单独抽 design token 文件）。

三、仓库与品牌资源

路径	说明
`apps/logo.png`	优雅草科技 Logo 主文件（更新品牌时请改此文件并同步下方两份拷贝）。
`apps/favicon.ico`	站点图标主文件。
`favicon.ico`（仓库根目录）	与 `apps/favicon.ico` 保持一致，便于根路径或文档场景引用。
`apps/pc-web/public/logo.png`、`public/favicon.ico`	PC 端构建用拷贝。
`apps/mobile/src/static/logo-yacyer.png`、`favicon.ico`	UniApp H5/各端静态资源拷贝。

更新 Logo / Favicon 后请执行（PowerShell 示例）：

Copy-Item apps\logo.png apps\pc-web\public\logo.png -Force
Copy-Item apps\favicon.ico apps\pc-web\public\favicon.ico -Force
Copy-Item apps\logo.png apps\mobile\src\static\logo-yacyer.png -Force
Copy-Item apps\favicon.ico apps\mobile\src\static\favicon.ico -Force
Copy-Item apps\favicon.ico favicon.ico -Force

PC 入口 HTML 已关联 favicon.ico；UniApp H5 模板已关联 /static/favicon.ico。

四、环境要求

Node.js：建议 20 LTS 或 22+ （内置 fetch，便于后台运行）。
npm：9+（支持 workspaces）。
DeepSeek：在 DeepSeek 开放平台申请 API Key；切勿将 Key 写入前端代码或提交到 Git。

五、安装依赖

在仓库根目录执行：

npm install

将安装 apps/mobile、apps/pc-web、apps/api 等 workspace 依赖。

六、运行方法（开发）

需同时或按需启动：后台 API、PC 前端 或 UniApp H5。

1. 配置后台环境变量

复制示例文件并编辑（不要把真实 Key 提交到仓库）：

copy apps\api.env.example apps\api.env

在 apps/api/.env 中至少配置：

变量	说明
`DEEPSEEK_API_KEY`	DeepSeek API 密钥（必填，仅服务端使用）。
`DEEPSEEK_MODEL`	可选，默认 `deepseek-v4-flash`；生产可选用 `deepseek-v4-pro`。
`DEEPSEEK_BASE_URL`	可选，默认 `https://api.deepseek.com`。
`PORT`	可选，默认 `8787`。
`CORS_ORIGINS`	生产环境建议配置为逗号分隔的前端域名；开发可不配。

2. 启动后台（gxc-api）

npm run dev:api

默认监听：http://127.0.0.1:8787
健康检查：GET http://127.0.0.1:8787/api/v1/health（返回 hasDeepseekKey 表示是否读到 Key）。

若报错 EADDRINUSE / 端口已被占用：说明本机 8787 上已有进程（服务器上多为 PM2 的 gxc-api 生产实例 与 npm run dev:api 抢同一端口）。二选一即可：① 先 pm2 stop gxc-api 再跑 npm run dev:api；② 保持 PM2 不动，开发改用其它端口：PORT=8788 npm run dev:api（同时要把本地 Vite 代理里的后端端口改成 8788，或仅在线上机器用方式①）。

3. 启动 PC 端

npm run dev:pc

apps/pc-web/vite.config.ts 中 /api 代理的 target 决定开发时请求发往何处（仓库内可能指向线上 API 或本机 http://127.0.0.1:8787）。若需纯本机联调，请将 target 改为本机 gxc-api 地址并执行 npm run dev:api，同时保证 apps/api/.env 已配置 DEEPSEEK_API_KEY。代理已加大 timeout，避免泛检索阶段被 Vite 提前断开。

4. 启动 UniApp（H5）

npm run dev:mobile

apps/mobile/vite.config.ts 同样配置了 /api 代理（target 与 timeout 与 PC 侧思路一致）。未设置 VITE_API_BASE_URL 时，H5 开发走相对路径 /api/... 经代理转发；与 §7.2 生产环境「写满 API 根域名」不同，请勿混淆。

5. 微信小程序（可选）

npm run dev:mobile:mp

编译产物在 apps/mobile/dist/dev/mp-weixin。使用 微信开发者工具 打开该目录；合法 request 域名须配置为已部署的 HTTPS API 地址（不支持本地 localhost）。

七、构建与打包（生产）

7.1 根目录打包命令一览

在仓库根目录执行（需先 npm install）：

命令	产物目录（默认）	说明
`npm run build:api`	`apps/api/dist/`	后端 Node 入口：`apps/api/dist/index.js`（含 `/api/v1/query/deepseek-summary` 与 `/api/v1/hr/public-insight`），服务器用 PM2 / systemd 运行。
`npm run build:pc`	`apps/pc-web/dist/`	PC 端静态资源（功能中心 + 公职人员 + 四类招考）；打包前须配置好 `VITE_API_BASE_URL`（见 §7.2）。
`npm run build:mobile:h5`	`apps/mobile/dist/build/h5/`（以终端输出为准）	UniApp H5（五入口 + 多页面路由）；打包前须配置 `VITE_API_BASE_URL`（见 §7.2）。
`npm run build:mp-weixin -w gxc-mobile`	`apps/mobile/dist/build/mp-weixin/`（以终端输出为准）	微信小程序；同样读取 `apps/mobile/.env.production` 中的 `VITE_API_BASE_URL`；合法 request 域名须含 API 主机名。

也可在 apps/mobile 目录下执行 npm run build:mp-weixin（已安装依赖前提下）。

7.2 前后端分离：前端打包前必须配置 API 根地址

生产环境下，前端不会再拼「与页面同源的 /api」去访问后端，而是使用环境变量 VITE_API_BASE_URL（在代码里经 apiPath() 与路径拼接）。

要改的文件（二选一或都改）：

文件	用途
`apps/pc-web/.env.production`	`npm run build:pc` 时生效。
`apps/mobile/.env.production`	`build:mobile:h5`、各小程序 `build:mp-*` 时生效。

填写规则（务必遵守）：

只写 API 根地址，不要写具体接口路径；不要末尾斜杠。

- 正确：VITE_API_BASE_URL=https://gxc.youyacao.com
- 错误：https://gxc.youyacao.com/、https://gxc.youyacao.com/api

必须是 HTTPS（与小程序合法域名、浏览器混合内容策略一致）。
改完后必须 重新执行对应的 build 命令，再上传/同步新的 dist；仅改 .env 不重新打包，线上页面仍用旧地址。
服务端 apps/api/.env 的 CORS_ORIGINS 必须包含你 PC 页面、H5 页面 的完整来源（如 https://www.xxx.com），否则浏览器会报跨域。
微信小程序：公众平台「request 合法域名」填的域名必须与 VITE_API_BASE_URL 的主机名一致（不要路径）。
开源或换环境时，可复制 apps/pc-web/.env.production.example、apps/mobile/.env.production.example 为同目录下的 .env.production 再改地址。

本地开发：不设置 VITE_API_BASE_URL 时，仍走 Vite /api → 127.0.0.1:8787 代理；若本地也要直连线上 API，可用各端支持的本地 env 文件设置同一变量，并在服务端 CORS_ORIGINS 中加入 http://localhost:5173 等。

7.3 产物与部署关系简述

API：把 apps/api/dist 连同根目录 node_modules（或服务器上 npm ci）与 apps/api/.env 放在服务器运行即可（见第八章、第十四章）。
PC / H5：把对应 dist 内全部文件发布到 Nginx 站点根目录或对象存储；无需在静态服务器上跑 Node。

部署 PC / H5 时，仍需 HTTPS、CORS 与第八章一致。

八、服务器部署教程（生产上线）

以下假设你有一台 Linux 云主机（推荐 Ubuntu 22.04 LTS）、已备案的域名，且本机已完成 npm install 与一次生产构建。示例域名请替换为你的真实域名。

8.1 部署架构建议

角色	示例域名	说明
API（Node）	`https://api.你的域名.com`	仅后端，给浏览器 / 小程序 / H5 调 `POST /api/...`。
PC 静态站	`https://www.你的域名.com` 或 `https://pc.你的域名.com`	`npm run build:pc` 产物，纯静态文件。
UniApp H5	`https://m.你的域名.com`	`npm run build:mobile:h5` 产物，纯静态或对象存储托管。

三者可同机部署（Nginx 分流），也可分机；小程序合法域名必须填 HTTPS 的 API 主机名。

8.2 服务器环境准备

# 安装 Node 20+（推荐使用 nvm 或发行版自带新版本）
node -v

# 安装 Nginx（用于 HTTPS 反代与静态站点）
sudo apt update && sudo apt install -y nginx

# 防火墙放行 HTTP/HTTPS（以 ufw 为例）
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable

将域名 DNS A 记录 指向服务器公网 IP。

8.3 拉取代码与安装依赖

sudo mkdir -p /opt/youyacaogxc && sudo chown $USER:$USER /opt/youyacaogxc
cd /opt/youyacaogxc
git clone <你的仓库地址> .
npm ci

8.4 配置 API 环境变量（勿提交仓库）

在服务器上创建 apps/api/.env（与本地相同变量名），至少包含：

NODE_ENV=production
PORT=8787
DEEPSEEK_API_KEY=你的密钥
DEEPSEEK_MODEL=deepseek-v4-flash
# 生产务必限制来源，逗号分隔多个前端域名，无空格或按你环境习惯
CORS_ORIGINS=https://www.你的域名.com,https://m.你的域名.com

安全：用 chmod 600 apps/api/.env 限制可读；不要将 .env 打进 Docker 镜像或 Git。

8.5 编译并启动 API

cd /opt/youyacaogxc
npm run build:api
NODE_ENV=production node apps/api/dist/index.js

默认监听 PORT（未设置则为 8787）。先用 curl -s http://127.0.0.1:8787/api/v1/health 确认 hasDeepseekKey 为 true。

推荐使用 PM2 常驻进程（服务器重启后自动拉起）：

sudo npm i -g pm2
cd /opt/youyacaogxc
pm2 start apps/api/dist/index.js --name gxc-api
pm2 save
pm2 startup

说明：apps/api 内 dotenv 会从 apps/api/.env 加载（与 cwd 无关），请保证该文件在服务器上存在。

8.6 Nginx 反向代理 API（HTTPS）

申请证书（Let's Encrypt 示例，需先让 api.你的域名.com 解析到本机）：

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d api.你的域名.com

站点配置示例 /etc/nginx/sites-available/gxc-api：

server {
    listen 443 ssl http2;
    server_name api.你的域名.com;

    # certbot 会自动写入 ssl_certificate 等指令；若手动配置请指向你的证书路径

    location / {
        proxy_pass http://127.0.0.1:8787;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_connect_timeout 60s;
        proxy_send_timeout 600s;
        proxy_read_timeout 600s;
        # PC 端对 /api/v1/query/deepseek-summary 会带 X-GXC-Stream:1，下行 NDJSON 心跳；关闭缓冲以免整段缓冲到模型结束才发往浏览器
        proxy_buffering off;
    }
}

sudo ln -sf /etc/nginx/sites-available/gxc-api /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

8.7 构建 PC 端并部署静态文件

在构建机或本机写好 apps/pc-web/.env.production（勿提交敏感信息时可只在 CI/服务器生成）：

VITE_API_BASE_URL=https://api.你的域名.com

npm run build:pc

将 apps/pc-web/dist/ 全部上传到服务器目录，例如 /var/www/gxc-pc/，Nginx 示例：

server {
    listen 443 ssl http2;
    server_name www.你的域名.com;
    root /var/www/gxc-pc;
    index index.html;
    location / {
        try_files $uri $uri/ /index.html;
    }
}

8.8 构建 UniApp H5 并部署

在 apps/mobile/ 下配置生产环境变量（与 Vite 约定一致，文件名可为 .env.production）：

VITE_API_BASE_URL=https://api.你的域名.com

npm run build:mobile:h5

产物一般在 apps/mobile/dist/build/h5/（以本机编译输出为准），将该目录静态部署到 m.你的域名.com 或对象存储 + CDN。

8.9 微信小程序「合法域名」

登录微信公众平台 → 开发 → 开发管理 → 服务器域名。
request 合法域名 填写：https://api.你的域名.com（与 VITE_API_BASE_URL 一致，无末尾斜杠）。
域名须备案且 HTTPS；保存后等待生效再真机调试。

8.10 上线检查清单

GET https://api.你的域名.com/api/v1/health 返回 ok: true 且 hasDeepseekKey: true
POST https://api.你的域名.com/api/v1/query/deepseek-summary 用 curl 或 Postman 带 JSON 测通
PC / H5 页面能完成一次查询，浏览器控制台无 CORS 报错（若有问题检查 CORS_ORIGINS）
小程序已配置合法域名并通过审核流程（如需要）

8.11 服务器上 Git 更新与 API 重启（发版流程）

适用于：代码已用 Git 托管，服务器上为 clone 下来的目录（如 /opt/youyacaogxc），API 使用 PM2 进程名 gxc-api（与第十四章一致；若进程名不同请替换）。

1）进入项目目录并拉取最新代码

cd /opt/youyacaogxc
git pull origin main

若主分支名为 master，将 main 改为 master。若有冲突，先本地解决再推送，服务器再 git pull。

2）安装依赖（推荐与 lockfile 一致）

npm ci

若无 package-lock.json 或希望宽松安装，可用 npm install。

3）若本次发版包含 Prompt / 服务端逻辑改动，重新构建 API

npm run build:api

4）重启 Node API（PM2）

pm2 restart gxc-api

查看是否报错、端口是否监听：

pm2 status
pm2 logs gxc-api --lines 80
curl -s https://你的API域名/api/v1/health

其他常用命令：

命令	作用
`pm2 reload gxc-api`	重载进程（与 restart 类似，按 PM2 版本略有差异）。
`pm2 stop gxc-api`	停止 API。
`pm2 delete gxc-api`	从 PM2 列表移除（需重新 `pm2 start`）。

5）若本次发版包含前端或环境变量变更

若修改了 VITE_API_BASE_URL：在构建机或服务器上改好 apps/pc-web/.env.production、apps/mobile/.env.production 后执行：
npm run build:pc / npm run build:mobile:h5（及需要的 build:mp-weixin）。
将新的 dist 同步到 Nginx 静态目录（覆盖旧文件），无需重启 Nginx（除非改动了站点配置）。
若仅改 服务端 .env（如 CORS_ORIGINS、DEEPSEEK_MODEL）：改完后执行 pm2 restart gxc-api 即可，不必 git pull（除非你把 .env 也纳入版本管理，一般不推荐）。

6）一键顺序示例（API + 三端全量，按需删减）

cd /opt/youyacaogxc
git pull origin main
npm ci
npm run build:api && npm run build:pc && npm run build:mobile:h5
pm2 restart gxc-api
# 再将 apps/pc-web/dist、apps/mobile/dist/build/h5 同步到各自站点目录

九、后台 API 说明（apps/api）

根路径 GET / 返回 JSON 中会列出主要接口键名（如 query、hrPublicInsight），便于运维探活时对照。

方法	路径	说明
`GET`	`/api/v1/health`	服务健康检查；含 `hasDeepseekKey` 等字段。
`POST`	`/api/v1/query/deepseek-summary`	公职人员公开线索查询。Body：`name` 与 `associated_region` 必填（`associated_region` 为关联地区自由文本，如市/县/乡镇或工作地、户籍地等，最长约 200 字）。兼容：未传 `associated_region` 但传了旧字段 `region` 时视为关联地区。`work`、`source_excerpt` 可选。分阶段：`stage` 省略或 `full` 为单次全量 JSON；`research` 返回 `candidate_persons` 等；`judgment` 须带 `research`，可选 `selected_candidate`。缺关联地区时 `ASSOCIATED_REGION_REQUIRED`。请求头 `X-GXC-Stream: 1` 时，响应为 `application/x-ndjson` 心跳流，结束帧 `type: "done"` 内为与原先一致的 JSON，用于减轻 CDN/网关在「长时间无下行」时约 20s 断连。移动端公职人员结果页已与 PC 对齐：同样发送 `X-GXC-Stream: 1`、`timeout: 300000`，且 `dataType: 'text'` 后按行解析 NDJSON（见 `apps/mobile/src/pages/result/result.vue`）。不传流式头时仍为单次 JSON。
`POST`	`/api/v1/hr/public-insight`	体制 / 编外招考 / 省考 / 国企招聘四类参考。Body：`kind` 必填，取值：`establishment_snapshot`

商业调用说明：计费与用量以 DeepSeek 官方控制台为准；服务端关闭 thinking 以降低时延与费用，模型 ID 建议按官方文档选用 V4 系列。

部署提示：若线上仍返回 NAME_AND_REGION_REQUIRED，说明运行中的 gxc-api 为旧构建。请在服务器仓库根目录执行 npm install（或 npm ci）后 npm run build（根目录已配置为编译 gxc-api），或进入 apps/api 再执行 npm run build；产物在 apps/api/dist/，确认 PM2 指向 apps/api/dist/index.js 后执行 pm2 restart gxc-api --update-env。若需同时构建 PC 与 H5，在根目录执行 npm run build:all（耗时更长）。

长请求与 Failed to fetch：泛检索、判定及 hr/public-insight 均可能需数十秒以上。部分 CDN/网关会在长时间无数据从源站下行到浏览器时约 20s 断开（Nginx access 常见 499），与源站 proxy_read_timeout 已设很大 可同时存在。PC 与 移动端公职人员 / 招考请求均应对 deepseek-summary、hr/public-insight 使用 X-GXC-Stream: 1，由 gxc-api 周期性输出 NDJSON 心跳；反代该 API 的 location 建议 proxy_buffering off，否则 Nginx 可能把上游响应缓冲到整段结束才发往客户端，心跳无法提前到达。仍请保留较大的 proxy_read_timeout / proxy_send_timeout，并视需要增大 client_max_body_size。环境变量 DEEPSEEK_FETCH_TIMEOUT_MS（默认 300000）控制服务端请求 DeepSeek 的超时。

查看日志（服务器 SSH） ：

Node / PM2：pm2 logs gxc-api --lines 100（实时，Ctrl+C 退出）；只看最近一段：pm2 logs gxc-api --lines 200 --nostream。进程信息：pm2 show gxc-api（可看启动脚本、工作目录、环境变量是否加载）。说明：gxc-api 在公职人员 deepseek-summary 与 hr/public-insight 请求开始、上游成功返回时会有对应日志（如 deepseek-summary begin、hr/public-insight begin 及 upstream ok … ms=）；若只有 begin 而无 upstream ok，多为上游仍等待或失败，请对照 Nginx access 状态码与 DEEPSEEK_API_KEY。
Nginx：宝塔常见 /www/wwwlogs/<域名>.error.log；或 grep -i timeout /www/wwwlogs/*.error.log | tail。系统 Nginx 也可能是 /var/log/nginx/error.log。

Nginx access 里常见状态码：GET / 若访问 只挂了 API 的域名，浏览器里不是官网页面（部署新版后根路径会返回 JSON 说明）；日常请打开 PC 站点域名（如 gxcpc.youyacao.com），接口走 POST /api/...。502 多为当时连不上 Node（未启动、崩溃、重启中）。400 多为请求体校验失败（如姓名为空、NAME_REQUIRED）。499 表示 客户端在响应完成前断开（用户刷新、外层网关、弱网等）；长耗时请求请配合 流式保活 与 proxy_buffering off，并查 CDN 是否有单独超时。

十、查询页合规提示（产品文案）

页眉下方显著横幅使用常量 HEADER_LEGAL_NOTICE_KICKER、HEADER_LEGAL_NOTICE_P1、HEADER_LEGAL_NOTICE_P2：PC 为全站顶栏下一条；移动端在功能中心、公职人员表单页（official）、公职人员结果页（result）、招考参考页（hr-insight）等均展示，明确「非官方政务系统、公开来源、反诈参考、未公开范围不予收录」等边界。

查询区与结果区另附一句话说明（常量 SOURCE_QUERY_DISCLAIMER）：

本页内容为合法公开信息之摘录与整理，仅供参考，不具任何身份核验法律效力；重要事项请登录政府官网或拨打对外公开的官方电话核实。

修改上述文案时请同步编辑：

apps/mobile/src/constants/brand.ts
apps/pc-web/src/constants/brand.ts

十一、根目录 npm 脚本一览

脚本	作用
`npm run dev:api`	启动后台开发服务。
`npm run dev:pc`	启动 PC 前端开发服务。
`npm run dev:mobile`	启动 UniApp H5 开发。
`npm run dev:mobile:mp`	编译微信小程序端。
`npm run build:api` / `build:pc` / `build:mobile:h5`	各端生产构建（详见第七章）。
`npm run build:all`	依次执行 `build:api` + `build:pc` + `build:mobile:h5`（发版全量时常用）。
`npm run build:mp-weixin -w gxc-mobile`	微信小程序生产包。

十二、常见问题

PC / H5 提示请求失败
先确认 gxc-api 已启动且 apps/api/.env 中 DEEPSEEK_API_KEY 正确；开发期若 Vite 代理指向线上 API，则无需本机 npm run dev:api。查看 pm2 logs gxc-api 或浏览器控制台网络面板中的 HTTP 状态码与响应体。
移动端「公职人员查询」一直失败或很快超时
微信小程序等默认 uni.request 超时偏短，且默认 dataType: 'json' 无法解析 NDJSON 流式整段响应。当前仓库已在 pages/result/result.vue 中为 deepseek-summary 设置 timeout: 300000、X-GXC-Stream: 1、dataType: 'text' 并复用与 PC 一致的 parseQueryResponseBody 解析逻辑。若你自行改过该页，请对照仓库版本恢复上述三项。

2b. 公职人员查询正常，但人事招考类（体制结构 / 编外 / 省考 / 国企）报错，响应里出现 404 Not Found
说明线上 gxc-api 仍是旧构建，尚未包含 POST /api/v1/hr/public-insight 路由（与 /api/v1/query/deepseek-summary 不是同一路径）。请在 API 服务器拉取最新代码后执行 npm run build:api（或根目录 npm run build:all），再 pm2 restart gxc-api --update-env。若经 Nginx 反代，确认 location /api/ 指向当前 Node 进程且未单独拦截 /api/v1/hr/。

小程序无法访问接口
小程序只能请求已在公众平台配置的 HTTPS 域名；VITE_API_BASE_URL 的主机名须与合法域名一致。
CORS 错误（生产环境）
在 apps/api/.env 设置 CORS_ORIGINS，包含 PC 站点与 H5 站点完整来源（如 https://gxcpc.youyacao.com、https://gxch5.youyacao.com），逗号分隔。
HBuilderX 提示找不到 apps/mobile/node_modules
本仓库为 npm workspaces，依赖默认安装在仓库根 node_modules。在根目录执行 npm install 后会自动运行 postinstall，在 apps/mobile/node_modules 创建指向根目录的联接（Windows 为 junction），再于 HBX 中打开 apps/mobile 即可。若仍报错，可手动执行：node scripts/prepare-mobile-hbx.mjs。

十三、版权声明与致谢

本项目数据与展示边界以政务公开与相关法律法规为准。大模型能力由 DeepSeek 提供，调用需遵守其服务条款与计费规则。

优雅草科技与创始人卓伊凡秉行「侠之大者，为国为民」——以技术向善，在合法公开信息边界内服务公众防诈与知情权，与官方权威认定渠道形成合力而非替代关系。

十四、简易部署流程（服务器已装 Git，且账户可 clone 仓库）

适用于：Linux 服务器已安装 Git、当前登录用户已配置好 clone 权限（SSH 公钥已加到代码平台，或已登录有权限的 HTTPS 凭据），希望最少步骤把 API 跑起来；Nginx / HTTPS / 域名细节仍以 第八章 为准，此处不重复。

14.1 一键式命令流（在服务器上执行）

将 <仓库地址> 换成你的 git@... 或 https://... 克隆 URL，将部署目录按需修改（示例 /opt/youyacaogxc）。

# 1）进入部署目录并克隆（若目录已存在可先备份或换名）
sudo mkdir -p /opt/youyacaogxc && sudo chown "$USER":"$USER" /opt/youyacaogxc
cd /opt/youyacaogxc
git clone <仓库地址> .

# 2）安装依赖（生产推荐 ci，版本与 lockfile 一致）
npm ci

# 3）写入 API 环境变量（首次从本机复制 apps/api/.env 亦可）
cp apps/api/.env.example apps/api/.env
nano apps/api/.env   # 填写 DEEPSEEK_API_KEY、CORS_ORIGINS、PORT 等
chmod 600 apps/api/.env

# 4）生产构建（至少先构建 API；前端按需要再加）
npm run build:api

# 5）先前台试跑（Ctrl+C 即停），确认健康检查
node apps/api/dist/index.js
# 另开终端：curl -s http://127.0.0.1:8787/api/v1/health

确认无误后，用 PM2 常驻（需已 npm i -g pm2）：

cd /opt/youyacaogxc
pm2 start apps/api/dist/index.js --name gxc-api
pm2 save
pm2 startup    # 按提示执行一条命令，实现开机自启

14.2 后续与前端

反代与 HTTPS：按 第八章 §8.6 把 api.你的域名 指到本机 PORT。
服务器上 Git 更新与重启：见 第八章 §8.11（git pull → npm ci → build:api → pm2 restart gxc-api 等）。
PC / H5 打包与 API 地址：见 第七章 §7.1、§7.2；构建后将 dist 同步到 Nginx（第八章 §8.7、§8.8）。

14.3 克隆权限说明（私有仓库）

SSH：服务器用户 ~/.ssh/id_ed25519（或 rsa）公钥加入 GitHub / Gitee / 自建 Git 的 Deploy keys 或账户 SSH Keys。
HTTPS：使用个人访问令牌（PAT）或平台提供的只读 Deploy Token，避免在服务器上保存账号密码明文。