@whyour/qinglong 2.20.2-3 → 2.21.0-10

package/.env.example

@@ -1,6 +1,11 @@
 GRPC_PORT=5500
 BACK_PORT=5700
 
+# 服务绑定地址，默认 ::（IPv6 通配，双栈系统同时支持 IPv4/IPv6）
+# 纯 IPv4 环境自动 fallback 到 0.0.0.0，也可手动指定
+# BIND_HOST=0.0.0.0
+# BIND_HOST_GRPC=0.0.0.0
+
 LOG_LEVEL='info'
 
 JWT_SECRET=

package/AGENTS.md

@@ -0,0 +1,43 @@
+<!-- gitnexus:start -->
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **qinglong** (2778 symbols, 6698 relationships, 233 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> Index stale? Run `node .gitnexus/run.cjs analyze` from the project root — it auto-selects an available runner. No `.gitnexus/run.cjs` yet? `npx gitnexus analyze` (npm 11 crash → `npm i -g gitnexus`; #1939).
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows. For regression review, compare against the default branch: `detect_changes({scope: "compare", base_ref: "develop"})`.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `context({name: "symbolName"})`.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `rename` which understands the call graph.
+- NEVER commit changes without running `detect_changes()` to check affected scope.
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/qinglong/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/qinglong/clusters` | All functional areas |
+| `gitnexus://repo/qinglong/processes` | All execution flows |
+| `gitnexus://repo/qinglong/process/{name}` | Step-by-step execution trace |
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+<!-- gitnexus:end -->

package/README-en.md

@@ -48,6 +48,17 @@ docker pull whyour/qinglong:latest
 docker pull whyour/qinglong:debian
 ```
 
+When running the `debian` image as a non-root user, specify `--user qinglong`:
+
+```bash
+docker run -d \
+  -v /path/to/ql/data:/ql/data \
+  -p 5700:5700 \
+  --user qinglong \
+  --name qinglong \
+  whyour/qinglong:debian
+```
+
 ### npm
 
 The npm version supports `debian/ubuntu/alpine` systems and requires `node/npm/python3/pip3/pnpm` to be installed.

package/README.md

@@ -50,6 +50,17 @@ docker pull whyour/qinglong:latest
 docker pull whyour/qinglong:debian
 ```
 
+使用 `debian` 镜像以非 root 用户运行时，需指定 `--user qinglong`：
+
+```bash
+docker run -d \
+  -v /path/to/ql/data:/ql/data \
+  -p 5700:5700 \
+  --user qinglong \
+  --name qinglong \
+  whyour/qinglong:debian
+```
+
 ### npm
 
 npm 版本支持 `debian/ubuntu/alpine` 系统，需要自行安装 `node/npm/python3/pip3/pnpm`

package/back/protos/api.proto

@@ -151,6 +151,7 @@ enum NotificationMode {
   chronocat = 18;
   ntfy = 19;
   wxPusherBot = 20;
+  wxPusherSpt = 21;
 }
 
 message NotificationInfo {
@@ -244,6 +245,8 @@ message NotificationInfo {
   optional string wxPusherBotAppToken = 66;
   optional string wxPusherBotTopicIds = 67;
   optional string wxPusherBotUids = 68;
+
+  optional string wxPusherSptList = 70;
 }
 
 message SystemNotifyRequest {

package/deploy/kubernetes/README.md

@@ -0,0 +1,81 @@
+# Kubernetes deployment
+
+This deploys Qinglong as a single-replica `StatefulSet` with persistent data at `/ql/data`.
+
+```bash
+kubectl apply -k deploy/kubernetes/overlays/local
+kubectl -n qinglong rollout status statefulset/qinglong
+```
+
+Open the panel locally:
+
+```bash
+kubectl -n qinglong port-forward svc/qinglong 5700:5700
+```
+
+Then visit <http://127.0.0.1:5700>.
+
+## Image registry overlays
+
+Use `overlays/example` as the committed template for registry customization:
+
+```yaml
+whyour/qinglong:debian -> registry.example.com/whyour/qinglong:debian
+```
+
+Create `overlays/local/kustomization.yaml` for the actual cluster image. The `local` overlay is ignored by git so private registry names, digests, and credentials-related references stay local.
+
+## Storage
+
+The manifest creates a 5 GiB `ReadWriteOnce` PVC from the cluster's default `StorageClass`.
+If your cluster has no default storage class, add `storageClassName` under:
+
+```yaml
+volumeClaimTemplates:
+  - metadata:
+      name: data
+    spec:
+      storageClassName: your-storage-class
+```
+
+Keep `replicas: 1`. Qinglong stores state in the persistent data directory, including SQLite files, so multiple replicas should not share the same data volume.
+
+## Ingress example
+
+If you expose Qinglong through an Ingress path other than `/`, set `QlBaseUrl` to the same path with leading and trailing slashes.
+
+```yaml
+env:
+  - name: QlBaseUrl
+    value: "/qinglong/"
+```
+
+Example Ingress:
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: qinglong
+  namespace: qinglong
+spec:
+  rules:
+    - host: qinglong.example.com
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: qinglong
+                port:
+                  number: 5700
+```
+
+## Maintenance commands
+
+```bash
+kubectl -n qinglong logs -f statefulset/qinglong
+kubectl -n qinglong exec -it statefulset/qinglong -- ql check
+kubectl -n qinglong exec -it statefulset/qinglong -- ql update
+```

package/deploy/kubernetes/base/kustomization.yaml

@@ -0,0 +1,5 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - qinglong.yaml

package/deploy/kubernetes/base/qinglong.yaml

@@ -0,0 +1,95 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: qinglong
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: qinglong
+  namespace: qinglong
+  labels:
+    app.kubernetes.io/name: qinglong
+spec:
+  type: ClusterIP
+  selector:
+    app.kubernetes.io/name: qinglong
+  ports:
+    - name: http
+      port: 5700
+      targetPort: http
+---
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: qinglong
+  namespace: qinglong
+  labels:
+    app.kubernetes.io/name: qinglong
+spec:
+  serviceName: qinglong
+  replicas: 1
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: qinglong
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: qinglong
+    spec:
+      securityContext:
+        fsGroup: 5432
+        fsGroupChangePolicy: OnRootMismatch
+      containers:
+        - name: qinglong
+          image: whyour/qinglong:debian
+          imagePullPolicy: IfNotPresent
+          env:
+            - name: QlBaseUrl
+              value: "/"
+            - name: TZ
+              value: Asia/Shanghai
+          ports:
+            - name: http
+              containerPort: 5700
+          readinessProbe:
+            httpGet:
+              path: /api/health
+              port: http
+            initialDelaySeconds: 20
+            periodSeconds: 10
+            timeoutSeconds: 3
+            failureThreshold: 6
+          livenessProbe:
+            httpGet:
+              path: /api/health
+              port: http
+            initialDelaySeconds: 60
+            periodSeconds: 20
+            timeoutSeconds: 3
+            failureThreshold: 6
+          startupProbe:
+            httpGet:
+              path: /api/health
+              port: http
+            periodSeconds: 5
+            timeoutSeconds: 3
+            failureThreshold: 60
+          resources:
+            requests:
+              cpu: 100m
+              memory: 256Mi
+            limits:
+              memory: 1Gi
+          volumeMounts:
+            - name: data
+              mountPath: /ql/data
+  volumeClaimTemplates:
+    - metadata:
+        name: data
+      spec:
+        accessModes:
+          - ReadWriteOnce
+        resources:
+          requests:
+            storage: 5Gi

package/deploy/kubernetes/overlays/example/kustomization.yaml

@@ -0,0 +1,10 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - ../../base
+
+images:
+  - name: whyour/qinglong
+    newName: registry.example.com/whyour/qinglong
+    newTag: debian

package/docker/Dockerfile

@@ -1,18 +1,13 @@
-FROM node:22-slim AS nodebuilder
-
-FROM python:3.11-slim-bookworm AS builder
+FROM python:3.11-alpine3.18 AS builder
 COPY package.json .npmrc pnpm-lock.yaml /tmp/build/
-COPY --from=nodebuilder /usr/local/bin/node /usr/local/bin/
-COPY --from=nodebuilder /usr/local/lib/node_modules/. /usr/local/lib/node_modules/
-RUN set -x && \
-  ln -s /usr/local/lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm && \
-  apt-get update && \
-  apt-get install --no-install-recommends -y libatomic1 && \
-  npm i -g pnpm@8.3.1 && \
-  cd /tmp/build && \
-  pnpm install --prod
-
-FROM python:3.11-slim-bookworm
+RUN set -x \
+  && apk update \
+  && apk add nodejs npm git \
+  && npm i -g pnpm@8.3.1 pm2 ts-node \
+  && cd /tmp/build \
+  && pnpm install --prod
+
+FROM python:3.11-alpine
 
 ARG QL_MAINTAINER="whyour"
 LABEL maintainer="${QL_MAINTAINER}"
@@ -22,67 +17,56 @@ ARG PYTHON_SHORT_VERSION=3.11
 
 ENV QL_DIR=/ql \
   QL_BRANCH=${QL_BRANCH} \
+  QL_CONTAINER=true \
   LANG=C.UTF-8 \
   SHELL=/bin/bash \
   PS1="\u@\h:\w \$ "
 
-ARG QL_UID=5432
-ARG QL_GID=5432
-RUN groupadd -g ${QL_GID} qinglong && \
-    useradd -m -u ${QL_UID} -g ${QL_GID} -s /bin/bash qinglong && \
-    mkdir -p /home/qinglong/bin /home/qinglong/.ssh && \
-    chmod 700 /home/qinglong/.ssh && \
-    chown -R ${QL_UID}:${QL_GID} /home/qinglong
-
-ENV QL_USER=qinglong
-ENV QL_HOME=/home/$QL_USER
-
-COPY --from=nodebuilder /usr/local/bin/node /usr/local/bin/
-COPY --from=nodebuilder /usr/local/lib/node_modules/. /usr/local/lib/node_modules/
-
-RUN set -x && \
-  ln -s /usr/local/lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm && \
-  ln -s /usr/local/lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx && \
-  apt-get update && \
-  apt-get upgrade -y && \
-  apt-get install --no-install-recommends -y git \
+VOLUME /ql/data
+
+EXPOSE 5700
+
+COPY --from=builder /usr/local/lib/node_modules/. /usr/local/lib/node_modules/
+COPY --from=builder /usr/local/bin/. /usr/local/bin/
+
+RUN set -x \
+  && apk update -f \
+  && apk upgrade \
+  && apk --no-cache add -f bash \
+  coreutils \
+  git \
   curl \
   wget \
   tzdata \
   perl \
   openssl \
-  openssh-client \
+  nodejs \
   jq \
+  openssh \
   procps \
   netcat-openbsd \
   unzip \
-  libatomic1 && \
-  apt-get clean && \
-  ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime && \
-  echo "Asia/Shanghai" >/etc/timezone && \
-  git config --global user.email "qinglong@users.noreply.github.com" && \
-  git config --global user.name "qinglong" && \
-  git config --global http.postBuffer 524288000 && \
-  npm install -g pnpm@8.3.1 pm2 ts-node && \
-  rm -rf /root/.cache && \
-  rm -rf /root/.npm && \
-  rm -rf /etc/apt/apt.conf.d/docker-clean && \
-  ulimit -c 0
-
-RUN mkdir -p ${QL_DIR} && \
-  chown -R ${QL_UID}:${QL_GID} ${QL_DIR}
-
-USER qinglong
+  npm \
+  && rm -rf /var/cache/apk/* \
+  && apk update \
+  && ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \
+  && echo "Asia/Shanghai" > /etc/timezone \
+  && git config --global user.email "qinglong@users.noreply.github.com" \
+  && git config --global user.name "qinglong" \
+  && git config --global http.postBuffer 524288000 \
+  && rm -rf /root/.cache \
+  && ulimit -c 0
+
 ARG SOURCE_COMMIT
-RUN git clone --depth=1 -b ${QL_BRANCH} ${QL_URL} ${QL_DIR} && \
-  cd ${QL_DIR} && \
-  cp -f .env.example .env && \
-  chmod 777 ${QL_DIR}/shell/*.sh && \
-  chmod 777 ${QL_DIR}/docker/*.sh && \
-  git clone --depth=1 -b ${QL_BRANCH} https://github.com/${QL_MAINTAINER}/qinglong-static.git /tmp/static && \
-  mkdir -p ${QL_DIR}/static && \
-  cp -rf /tmp/static/* ${QL_DIR}/static && \
-  rm -rf /tmp/static
+RUN git clone --depth=1 -b ${QL_BRANCH} ${QL_URL} ${QL_DIR} \
+  && cd ${QL_DIR} \
+  && cp -f .env.example .env \
+  && chmod 777 ${QL_DIR}/shell/*.sh \
+  && chmod 777 ${QL_DIR}/docker/*.sh \
+  && git clone --depth=1 -b ${QL_BRANCH} https://github.com/${QL_MAINTAINER}/qinglong-static.git /static \
+  && mkdir -p ${QL_DIR}/static \
+  && cp -rf /static/* ${QL_DIR}/static \
+  && rm -rf /static
 
 ENV PNPM_HOME=${QL_DIR}/data/dep_cache/node \
   PYTHON_HOME=${QL_DIR}/data/dep_cache/python3 \
@@ -90,23 +74,21 @@ ENV PNPM_HOME=${QL_DIR}/data/dep_cache/node \
   HOME=/root
 
 ENV PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:${PNPM_HOME}:${PYTHON_HOME}/bin:${HOME}/bin \
-  NODE_PATH=/usr/local/bin:/usr/local/lib/node_modules:${PNPM_HOME}/global/5/node_modules \
+  NODE_PATH=/usr/local/bin:/usr/local/lib/node_modules \
   PIP_CACHE_DIR=${PYTHON_HOME}/pip \
   PYTHONPATH=${PYTHON_HOME}:${PYTHON_HOME}/lib/python${PYTHON_SHORT_VERSION}:${PYTHON_HOME}/lib/python${PYTHON_SHORT_VERSION}/site-packages
 
 RUN pip3 install --prefix ${PYTHON_HOME} requests
 
-COPY --chown=qinglong:qinglong --from=builder /tmp/build/node_modules/. /ql/node_modules/
+COPY --from=builder /tmp/build/node_modules/. /ql/node_modules/
 
-USER root
+RUN ln -sf ${QL_DIR}/shell/task.sh /usr/local/bin/task \
+  && ln -sf ${QL_DIR}/shell/update.sh /usr/local/bin/ql \
+  && chmod +x /usr/local/bin/task /usr/local/bin/ql
 
 WORKDIR ${QL_DIR}
 
 HEALTHCHECK --interval=5s --timeout=2s --retries=20 \
-  CMD curl -sf --noproxy '*' http://127.0.0.1:5700/api/health || exit 1
+  CMD curl -sf --noproxy '*' http://localhost:${QlPort:-5700}/api/health || exit 1
 
 ENTRYPOINT ["./docker/docker-entrypoint.sh"]
-
-VOLUME /ql/data
-  
-EXPOSE 5700

package/docker/Dockerfile.310

@@ -0,0 +1,94 @@
+FROM python:3.10-alpine3.18 AS builder
+COPY package.json .npmrc pnpm-lock.yaml /tmp/build/
+RUN set -x \
+  && apk update \
+  && apk add nodejs npm git \
+  && npm i -g pnpm@8.3.1 pm2 ts-node \
+  && cd /tmp/build \
+  && pnpm install --prod
+
+FROM python:3.10-alpine
+
+ARG QL_MAINTAINER="whyour"
+LABEL maintainer="${QL_MAINTAINER}"
+ARG QL_URL=https://github.com/${QL_MAINTAINER}/qinglong.git
+ARG QL_BRANCH=develop
+ARG PYTHON_SHORT_VERSION=3.10
+
+ENV QL_DIR=/ql \
+  QL_BRANCH=${QL_BRANCH} \
+  QL_CONTAINER=true \
+  LANG=C.UTF-8 \
+  SHELL=/bin/bash \
+  PS1="\u@\h:\w \$ "
+
+VOLUME /ql/data
+
+EXPOSE 5700
+
+COPY --from=builder /usr/local/lib/node_modules/. /usr/local/lib/node_modules/
+COPY --from=builder /usr/local/bin/. /usr/local/bin/
+
+RUN set -x \
+  && apk update -f \
+  && apk upgrade \
+  && apk --no-cache add -f bash \
+  coreutils \
+  git \
+  curl \
+  wget \
+  tzdata \
+  perl \
+  openssl \
+  nodejs \
+  jq \
+  openssh \
+  procps \
+  netcat-openbsd \
+  unzip \
+  npm \
+  && rm -rf /var/cache/apk/* \
+  && apk update \
+  && ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \
+  && echo "Asia/Shanghai" > /etc/timezone \
+  && git config --global user.email "qinglong@users.noreply.github.com" \
+  && git config --global user.name "qinglong" \
+  && git config --global http.postBuffer 524288000 \
+  && rm -rf /root/.cache \
+  && ulimit -c 0
+
+ARG SOURCE_COMMIT
+RUN git clone --depth=1 -b ${QL_BRANCH} ${QL_URL} ${QL_DIR} \
+  && cd ${QL_DIR} \
+  && cp -f .env.example .env \
+  && chmod 777 ${QL_DIR}/shell/*.sh \
+  && chmod 777 ${QL_DIR}/docker/*.sh \
+  && git clone --depth=1 -b ${QL_BRANCH} https://github.com/${QL_MAINTAINER}/qinglong-static.git /static \
+  && mkdir -p ${QL_DIR}/static \
+  && cp -rf /static/* ${QL_DIR}/static \
+  && rm -rf /static
+
+ENV PNPM_HOME=${QL_DIR}/data/dep_cache/node \
+  PYTHON_HOME=${QL_DIR}/data/dep_cache/python3 \
+  PYTHONUSERBASE=${QL_DIR}/data/dep_cache/python3 \
+  HOME=/root
+
+ENV PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:${PNPM_HOME}:${PYTHON_HOME}/bin:${HOME}/bin \
+  NODE_PATH=/usr/local/bin:/usr/local/lib/node_modules \
+  PIP_CACHE_DIR=${PYTHON_HOME}/pip \
+  PYTHONPATH=${PYTHON_HOME}:${PYTHON_HOME}/lib/python${PYTHON_SHORT_VERSION}:${PYTHON_HOME}/lib/python${PYTHON_SHORT_VERSION}/site-packages
+
+RUN pip3 install --prefix ${PYTHON_HOME} requests
+
+COPY --from=builder /tmp/build/node_modules/. /ql/node_modules/
+
+RUN ln -sf ${QL_DIR}/shell/task.sh /usr/local/bin/task \
+  && ln -sf ${QL_DIR}/shell/update.sh /usr/local/bin/ql \
+  && chmod +x /usr/local/bin/task /usr/local/bin/ql
+
+WORKDIR ${QL_DIR}
+
+HEALTHCHECK --interval=5s --timeout=2s --retries=20 \
+  CMD curl -sf --noproxy '*' http://localhost:${QlPort:-5700}/api/health || exit 1
+
+ENTRYPOINT ["./docker/docker-entrypoint.sh"]