From 161e34a963f743a5b6dc9b5ae64c1c6fae609973 Mon Sep 17 00:00:00 2001
From: brooklin <brooklin@tencent.com>
Date: Wed, 13 May 2026 11:23:02 +0800
Subject: [PATCH 1/3] docs: add codecc subpath support design

---
 .../specs/2026-05-13-codecc-subpath-design.md | 188 ++++++++++++++++++
 1 file changed, 188 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-05-13-codecc-subpath-design.md

diff --git a/docs/superpowers/specs/2026-05-13-codecc-subpath-design.md b/docs/superpowers/specs/2026-05-13-codecc-subpath-design.md
new file mode 100644
index 00000000..21c8bac4
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-13-codecc-subpath-design.md
@@ -0,0 +1,188 @@
+# CodeCC Frontend Subpath Support Design
+
+Date: 2026-05-13
+
+## Background
+
+CodeCC frontend currently assumes that the application is served from the domain root in several places. The frontend uses Vue Router history mode with no router base, production `index.html` extracts project id from paths that start with `/codecc/`, login callback uses `/static/login_success.html`, and the project cookie is written with `path=/`.
+
+The target is to support arbitrary deploy-time subpaths such as `/`, `/codecc/`, or `/bk/codecc/`, while keeping one reusable frontend image/package across environments.
+
+This design follows the iWiki "support subpath deployment" guidance and the bk-job subpath commit pattern:
+
+- inject path globals in `index.html`;
+- use one variable for web route base;
+- use one variable for static assets;
+- set webpack public path at runtime before other frontend imports;
+- keep API URLs explicit.
+
+## Goals
+
+- Support arbitrary deploy-time site paths with normalized values: `/` or `/path/`.
+- Preserve current root-path behavior when no subpath is configured.
+- Keep static asset prefix independent from route prefix so future CDN/static hosting changes do not require route changes.
+- Avoid broad route-table rewrites; use Vue Router base for history mode.
+- Provide a concrete verification path for build output, local subpath serving, and business smoke testing.
+
+## Non-Goals
+
+- This design does not move CodeCC backend API endpoints under the site subpath. API requests continue to use the configured `AJAX_URL_PREFIX`, which is `/ms` in production today.
+- This design does not rewrite BlueKing CI, Stream, IAM, PaaS, or external product URLs with CodeCC's site path. Those URLs are separate applications.
+- This design does not change business route names, route params, or page structure.
+
+## Path Model
+
+Two deploy-time variables define the behavior:
+
+- `BK_SITE_PATH`: the web application mount path. It controls Vue Router history base, internal absolute links, login callback path, and cookie scope.
+- `BK_STATIC_URL`: the static asset base URL. It controls webpack chunks, generated script/style references, favicon, and files under `static/`.
+
+Both values must be normalized to `/` or a leading-and-trailing slash path such as `/codecc/`. Empty strings, missing values, and invalid single-sided slashes are normalized before use.
+
+`BK_STATIC_URL` may equal `BK_SITE_PATH` for normal subpath deployment. It remains separate to allow static resources to move to another prefix later.
+
+## Frontend Design
+
+### Entry HTML
+
+`src/frontend/devops-codecc/index.html` should inject both variables:
+
+- `window.BK_SITE_PATH` from `process.env.BK_SITE_PATH`, defaulting to `/`;
+- `window.BK_STATIC_URL` from `process.env.BK_STATIC_URL`, defaulting to `window.BK_SITE_PATH` when empty.
+
+The entry page should define `window.__loadAssetsUrl__(src)` and use it for favicon, generated JavaScript, generated CSS, and static files that are loaded outside webpack module resolution.
+
+The production project-id extraction should strip `BK_SITE_PATH` before matching `codecc/:projectId`. This keeps the current behavior for `/codecc/demo/task/list` and adds support for `/bk/codecc/codecc/demo/task/list`.
+
+The `X-DEVOPS-PROJECT-ID` cookie should use `path=BK_SITE_PATH` instead of `path=/` so multiple mounted apps on the same host do not accidentally share the cookie.
+
+### Runtime Public Path
+
+Add `src/frontend/devops-codecc/static/webpack_public_path.js` and import it as the first import in `src/frontend/devops-codecc/src/main.js`.
+
+The file sets webpack runtime public path from `window.BK_STATIC_URL`. This ensures async chunks and webpack-managed assets resolve under the deploy-time static prefix.
+
+Webpack-managed assets imported from JavaScript or CSS should stay as imports or relative CSS URLs. Only manually constructed absolute static URLs need to be routed through `__loadAssetsUrl__` or a helper.
+
+### Path Helpers
+
+Add a small frontend utility for path handling so slash normalization is not repeated:
+
+- `normalizeBasePath(value)`: returns `/` or `/path/`;
+- `joinUrl(base, path)`: joins path fragments without duplicate or missing slashes;
+- `withSitePath(path)`: prefixes a CodeCC internal absolute path with `BK_SITE_PATH`;
+- `withStaticUrl(path)`: prefixes a static path with `BK_STATIC_URL`.
+
+The global `window.__loadAssetsUrl__` can use the same logic inline in `index.html`; JavaScript modules can use the helper directly.
+
+### Router
+
+`src/frontend/devops-codecc/src/router/index.js` should keep the route table unchanged and configure Vue Router as:
+
+- `mode: 'history'`;
+- `base: window.BK_SITE_PATH || '/'`;
+- existing `routes`.
+
+Keeping routes such as `/codecc/:projectId/task/list` avoids broad route churn. The browser URL becomes `<BK_SITE_PATH>/codecc/:projectId/task/list`.
+
+### Manual URL Call Sites
+
+The implementation should audit manual URL construction and only change CodeCC-owned URLs:
+
+- login modal success callback in `src/frontend/devops-codecc/src/api/index.js` should use the static prefix for `static/login_success.html`;
+- places using `window.location.origin + routerResolvedHref` for CodeCC internal pages should be verified after adding router base, because `router.resolve(...).href` should already include the base;
+- PaaS test report links that manually construct `/codecc/...` should use the site path helper when the URL points back to CodeCC;
+- CI/Stream/IAM/PaaS links should continue to use their existing product base URLs.
+
+The iframe `devops-utils.js` loader in `index.html` should keep using `BK_CI_PUBLIC_PATH_PREFIX` or `DEVOPS_SITE_URL`, but it should avoid treating a non-rendered placeholder as a valid URL.
+
+## Deployment Design
+
+Add `BK_SITE_PATH` to deploy-time configuration:
+
+- `src/frontend/devops-codecc/.bk.production.env`;
+- `scripts/deploy-codecc/codecc.properties`;
+- `docker-images/core/codecc/gateway/scripts/codecc.env`;
+- `helm-charts/core/codecc/templates/gateway/deployment.yaml`.
+
+Default value is `/`.
+
+For normal subpath deployment, set both:
+
+- `BK_SITE_PATH=/your/path/`;
+- `BK_PUBLIC_PATH_PREFIX=/your/path/`, which feeds the existing `BK_STATIC_URL` path.
+
+The existing gateway startup flow already renders `/data/workspace/frontend/index.html`, so it can continue to inject deployment values into the built frontend entry file.
+
+## Gateway Design
+
+`support-files/codecc/templates/core/gateway#core#vhosts#codecc.frontend.conf` should serve the same frontend under both root and configured subpath.
+
+Required behavior:
+
+- static files under the configured site path return the matching file from `$static_dir_codecc`;
+- history-mode page refreshes under the site path fall back to `index.html`;
+- root deployment continues to work unchanged;
+- `/ms/...` backend API proxying remains available at its current path.
+
+If a future deployment requires APIs under the same subpath, that should be a separate change because it affects `AJAX_URL_PREFIX`, websocket URLs, and backend nginx locations together.
+
+## Verification Plan
+
+### Build Output
+
+Build twice:
+
+- root mode: `BK_SITE_PATH=/` and `BK_STATIC_URL=/`;
+- subpath mode: `BK_SITE_PATH=/codecc-demo/` and `BK_STATIC_URL=/codecc-demo/`.
+
+Check the generated `dist/index.html`:
+
+- `window.BK_SITE_PATH` is normalized;
+- `window.BK_STATIC_URL` is normalized;
+- favicon, scripts, styles, and static callback path use the expected prefix;
+- generated runtime/chunk paths do not point to the domain root in subpath mode.
+
+### Local Static Serving
+
+Serve the same `dist` at `/codecc-demo/` using a small nginx or Express static server with history fallback.
+
+Open and refresh:
+
+- `/codecc-demo/codecc/demo/task/list`;
+- `/codecc-demo/codecc/demo/task/123/detail`;
+- `/codecc-demo/403` and an unknown route.
+
+Inspect Network:
+
+- entry JavaScript and CSS load from `/codecc-demo/`;
+- async chunks load from `/codecc-demo/`;
+- `static/login_success.html` loads from `/codecc-demo/static/login_success.html`;
+- page refresh returns `index.html` rather than a 404.
+
+### Business Smoke
+
+In an environment with backend access or mocks:
+
+- current-user request and CSRF header injection still work;
+- task list, task detail, defect list, checker set, and ignore pages route correctly;
+- `X-DEVOPS-PROJECT-ID` is set for the configured path;
+- 401 login modal uses a callback URL under the static prefix;
+- internal new-window links do not duplicate or drop the site path;
+- external CI/Stream/IAM/PaaS links remain unchanged.
+
+## Risks and Mitigations
+
+- Internal links built with `window.location.origin` may be inconsistent. Mitigation: audit all CodeCC-owned manual URL call sites and prefer router-resolved hrefs with the configured router base.
+- Some static references may be hidden in templates or string literals. Mitigation: search for `/static`, `static/`, `location.origin`, and `window.open` during implementation and verify through Network.
+- Deployment may configure `BK_SITE_PATH` and `BK_PUBLIC_PATH_PREFIX` inconsistently. Mitigation: document that normal subpath deployment sets both to the same normalized value unless static assets intentionally use another prefix.
+- API subpath support may be requested later. Mitigation: keep the current design explicit that API remains controlled by `AJAX_URL_PREFIX`, so a future API-path change can be scoped separately.
+
+## Acceptance Criteria
+
+- CodeCC works from `/` exactly as before.
+- CodeCC works from an arbitrary configured subpath without rebuilding for that specific path.
+- Deep-link refreshes under the subpath load the frontend app.
+- Webpack async chunks and static files load under `BK_STATIC_URL`.
+- Vue Router navigation and router-resolved internal links include `BK_SITE_PATH`.
+- Login callback and project cookie behavior work under the configured subpath.

From a275c864494abb11e8b4c37bbd40cbf7f41cc4a5 Mon Sep 17 00:00:00 2001
From: brooklin <brooklin@tencent.com>
Date: Wed, 13 May 2026 11:36:48 +0800
Subject: [PATCH 2/3] docs: add codecc subpath implementation plan

---
 ...026-05-13-codecc-subpath-implementation.md | 1012 +++++++++++++++++
 1 file changed, 1012 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-05-13-codecc-subpath-implementation.md

diff --git a/docs/superpowers/plans/2026-05-13-codecc-subpath-implementation.md b/docs/superpowers/plans/2026-05-13-codecc-subpath-implementation.md
new file mode 100644
index 00000000..9efd8b58
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-13-codecc-subpath-implementation.md
@@ -0,0 +1,1012 @@
+# CodeCC Frontend Subpath Support Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make CodeCC frontend work when deployed at `/` or any configured subpath such as `/codecc-demo/`, without rebuilding per environment.
+
+**Architecture:** Inject `BK_SITE_PATH` and `BK_STATIC_URL` in the rendered entry HTML, normalize both at runtime, and let Vue Router use `BK_SITE_PATH` as its history base. Use webpack runtime public path plus a small URL helper so static assets, login callback URLs, internal links, and project cookie path respect the configured deployment path while backend API URLs remain controlled by `AJAX_URL_PREFIX`.
+
+**Tech Stack:** Vue 2.7, Vue Router 3, bk-cli-service-webpack, webpack runtime public path, nginx/OpenResty gateway templates, Helm templates, shell deployment env rendering.
+
+---
+
+## File Structure
+
+- Create `src/frontend/devops-codecc/static/webpack_public_path.js`: sets webpack runtime public path before app imports.
+- Create `src/frontend/devops-codecc/src/utils/path.js`: shared path normalization and URL joining helpers for JavaScript modules.
+- Create `src/frontend/devops-codecc/scripts/verify-path-utils.js`: Node verifier for path helpers.
+- Modify `src/frontend/devops-codecc/index.html`: inject `BK_SITE_PATH`, normalize entry-page globals, define `__loadAssetsUrl__`, fix project-id cookie path, and fix iframe utility prefix handling.
+- Modify `src/frontend/devops-codecc/src/main.js`: import runtime public path before all other imports.
+- Modify `src/frontend/devops-codecc/src/router/index.js`: configure Vue Router history base.
+- Modify `src/frontend/devops-codecc/src/api/index.js`: build login modal success callback with the static asset prefix.
+- Modify CodeCC-owned internal URL call sites that manually construct root-relative URLs:
+  - `src/frontend/devops-codecc/src/views/paas/test/design-report.vue`
+  - any additional call sites found by the audit command in Task 4.
+- Modify deploy-time env sources:
+  - `src/frontend/devops-codecc/.bk.production.env`
+  - `scripts/deploy-codecc/codecc.properties`
+  - `docker-images/core/codecc/gateway/scripts/codecc.env`
+  - `helm-charts/core/codecc/templates/gateway/deployment.yaml`
+- Modify `support-files/codecc/templates/core/gateway#core#vhosts#codecc.frontend.conf`: strip the configured site path before frontend `try_files` checks.
+- Create `src/frontend/devops-codecc/scripts/verify-subpath-dist.js`: local build-output verifier for root and subpath modes.
+- Create `src/frontend/devops-codecc/scripts/serve-subpath-dist.js`: local static server with history fallback for manual browser verification.
+
+## Task 1: Add Path Helpers
+
+**Files:**
+- Create: `src/frontend/devops-codecc/src/utils/path.js`
+- Create: `src/frontend/devops-codecc/scripts/verify-path-utils.js`
+
+- [ ] **Step 1: Write the failing path helper verifier**
+
+Create `src/frontend/devops-codecc/scripts/verify-path-utils.js`:
+
+```js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const vm = require('vm');
+
+const sourcePath = path.resolve(__dirname, '../src/utils/path.js');
+const source = fs.readFileSync(sourcePath, 'utf8');
+const transformedSource = source
+  .replace(/export function /g, 'function ')
+  .concat('\nmodule.exports = { normalizeBasePath, normalizeAssetBase, joinUrl, getSitePath, getStaticUrl, withSitePath, withStaticUrl };');
+
+const sandbox = {
+  module: { exports: {} },
+  exports: {},
+  window: {},
+  URL,
+};
+
+vm.runInNewContext(transformedSource, sandbox, { filename: sourcePath });
+
+const {
+  normalizeBasePath,
+  normalizeAssetBase,
+  joinUrl,
+  getSitePath,
+  getStaticUrl,
+  withSitePath,
+  withStaticUrl,
+} = sandbox.module.exports;
+
+assert.strictEqual(normalizeBasePath(), '/');
+assert.strictEqual(normalizeBasePath(''), '/');
+assert.strictEqual(normalizeBasePath('/'), '/');
+assert.strictEqual(normalizeBasePath('codecc'), '/codecc/');
+assert.strictEqual(normalizeBasePath('/codecc'), '/codecc/');
+assert.strictEqual(normalizeBasePath('codecc/'), '/codecc/');
+assert.strictEqual(normalizeBasePath('/bk/codecc/'), '/bk/codecc/');
+assert.strictEqual(normalizeAssetBase('https://cdn.example.com/codecc'), 'https://cdn.example.com/codecc/');
+
+assert.strictEqual(joinUrl('/codecc-demo/', '/static/login_success.html'), '/codecc-demo/static/login_success.html');
+assert.strictEqual(joinUrl('/', '/static/login_success.html'), '/static/login_success.html');
+assert.strictEqual(joinUrl('https://example.com/codecc/', '/static/a.js'), 'https://example.com/codecc/static/a.js');
+assert.strictEqual(joinUrl('/codecc-demo/', 'https://cdn.example.com/a.js'), 'https://cdn.example.com/a.js');
+
+sandbox.window.BK_SITE_PATH = '/codecc-demo/';
+sandbox.window.BK_STATIC_URL = '';
+assert.strictEqual(getSitePath(), '/codecc-demo/');
+assert.strictEqual(getStaticUrl(), '/codecc-demo/');
+assert.strictEqual(withSitePath('/codecc/demo/task/list'), '/codecc-demo/codecc/demo/task/list');
+assert.strictEqual(withStaticUrl('/static/login_success.html'), '/codecc-demo/static/login_success.html');
+
+sandbox.window.BK_STATIC_URL = '/static-prefix/';
+assert.strictEqual(getStaticUrl(), '/static-prefix/');
+assert.strictEqual(withStaticUrl('/static/login_success.html'), '/static-prefix/static/login_success.html');
+
+sandbox.window.BK_STATIC_URL = 'https://cdn.example.com/codecc';
+assert.strictEqual(getStaticUrl(), 'https://cdn.example.com/codecc/');
+assert.strictEqual(withStaticUrl('/static/login_success.html'), 'https://cdn.example.com/codecc/static/login_success.html');
+
+console.log('path utils verifier passed');
+```
+
+- [ ] **Step 2: Run the focused test and verify it fails**
+
+Run:
+
+```bash
+cd /Users/brooklin/project/github/bk-codecc/src/frontend/devops-codecc
+node scripts/verify-path-utils.js
+```
+
+Expected: FAIL with `ENOENT` because `src/utils/path.js` does not exist yet.
+
+- [ ] **Step 3: Implement the path helper**
+
+Create `src/frontend/devops-codecc/src/utils/path.js`:
+
+```js
+export function normalizeBasePath(value = '/') {
+  const rawValue = String(value || '/').trim();
+  if (!rawValue || rawValue === '/') {
+    return '/';
+  }
+
+  const normalized = rawValue.replace(/^\/+|\/+$/g, '');
+  return normalized ? `/${normalized}/` : '/';
+}
+
+export function normalizeAssetBase(value = '/', fallback = '/') {
+  const rawValue = String(value || fallback || '/').trim();
+  if (/^https?:\/\//.test(rawValue) || rawValue.startsWith('//')) {
+    return rawValue.endsWith('/') ? rawValue : `${rawValue}/`;
+  }
+  return normalizeBasePath(rawValue);
+}
+
+export function joinUrl(base = '/', path = '') {
+  const baseValue = String(base || '/');
+  const pathValue = String(path || '');
+
+  if (/^https?:\/\//.test(pathValue) || pathValue.startsWith('//')) {
+    return pathValue;
+  }
+
+  if (/^https?:\/\//.test(baseValue)) {
+    const url = new URL(baseValue);
+    url.pathname = [url.pathname, pathValue].join('/').replace(/\/+/g, '/');
+    return url.toString().replace(/\/$/, pathValue ? '' : '/');
+  }
+
+  const startsWithRoot = baseValue.startsWith('/');
+  const joined = [baseValue, pathValue]
+    .filter(item => item !== '')
+    .join('/')
+    .replace(/\/+/g, '/');
+  const result = startsWithRoot ? `/${joined.replace(/^\/+/, '')}` : joined;
+  return result || (startsWithRoot ? '/' : '');
+}
+
+export function getSitePath() {
+  return normalizeBasePath(window.BK_SITE_PATH || '/');
+}
+
+export function getStaticUrl() {
+  return normalizeAssetBase(window.BK_STATIC_URL, getSitePath());
+}
+
+export function withSitePath(path) {
+  return joinUrl(getSitePath(), path);
+}
+
+export function withStaticUrl(path) {
+  return joinUrl(getStaticUrl(), path);
+}
+```
+
+- [ ] **Step 4: Run the path helper verifier**
+
+Run:
+
+```bash
+cd /Users/brooklin/project/github/bk-codecc/src/frontend/devops-codecc
+node scripts/verify-path-utils.js
+```
+
+Expected: `path utils verifier passed`.
+
+- [ ] **Step 5: Commit Task 1**
+
+Run:
+
+```bash
+git add src/frontend/devops-codecc/src/utils/path.js src/frontend/devops-codecc/scripts/verify-path-utils.js
+git commit -m "feat(frontend): add subpath url helpers"
+```
+
+Expected: commit succeeds.
+
+## Task 2: Inject Entry Variables and Runtime Public Path
+
+**Files:**
+- Create: `src/frontend/devops-codecc/static/webpack_public_path.js`
+- Modify: `src/frontend/devops-codecc/index.html`
+- Modify: `src/frontend/devops-codecc/src/main.js`
+- Modify: `src/frontend/devops-codecc/.bk.production.env`
+
+- [ ] **Step 1: Add webpack runtime public path file**
+
+Create `src/frontend/devops-codecc/static/webpack_public_path.js`:
+
+```js
+__webpack_public_path__ = window.BK_STATIC_URL || '/';
+```
+
+- [ ] **Step 2: Import runtime public path before all app imports**
+
+Modify the top of `src/frontend/devops-codecc/src/main.js` so the first executable import is:
+
+```js
+import '../static/webpack_public_path';
+```
+
+Expected beginning of file:
+
+```js
+/**
+ * @file main entry
+ * @author blueking
+ */
+
+import '../static/webpack_public_path';
+import Vue from 'vue';
+```
+
+- [ ] **Step 3: Add `BK_SITE_PATH` to production env**
+
+Modify `src/frontend/devops-codecc/.bk.production.env`:
+
+```env
+BK_SITE_PATH = '__BK_SITE_PATH__'
+BK_STATIC_URL = '__BK_PUBLIC_PATH_PREFIX__'
+```
+
+Place `BK_SITE_PATH` immediately before `BK_STATIC_URL`.
+
+- [ ] **Step 4: Add entry-page path normalization and `__loadAssetsUrl__`**
+
+In `src/frontend/devops-codecc/index.html`, immediately before the current environment variable declarations inside the first `<script>`, add:
+
+```html
+      function normalizeBasePath(value) {
+        var rawValue = String(value || '/').trim();
+        if (!rawValue || rawValue === '/') {
+          return '/';
+        }
+        var normalized = rawValue.replace(/^\/+|\/+$/g, '');
+        return normalized ? '/' + normalized + '/' : '/';
+      }
+
+      function normalizeAssetBase(value, fallback) {
+        var rawValue = String(value || fallback || '/').trim();
+        if (/^https?:\/\//.test(rawValue) || rawValue.indexOf('//') === 0) {
+          return rawValue.charAt(rawValue.length - 1) === '/' ? rawValue : rawValue + '/';
+        }
+        return normalizeBasePath(rawValue);
+      }
+
+      function joinUrl(base, path) {
+        var baseValue = String(base || '/');
+        var pathValue = String(path || '');
+        if (/^https?:\/\//.test(pathValue) || pathValue.indexOf('//') === 0) {
+          return pathValue;
+        }
+        if (/^https?:\/\//.test(baseValue)) {
+          var url = new URL(baseValue);
+          url.pathname = [url.pathname, pathValue].join('/').replace(/\/+/g, '/');
+          return url.toString().replace(/\/$/, pathValue ? '' : '/');
+        }
+        var startsWithRoot = baseValue.indexOf('/') === 0;
+        var joined = [baseValue, pathValue]
+          .filter(function (item) { return item !== ''; })
+          .join('/')
+          .replace(/\/+/g, '/');
+        return startsWithRoot ? '/' + joined.replace(/^\/+/, '') : joined;
+      }
+
+      var BK_SITE_PATH = normalizeBasePath('<%= process.env.BK_SITE_PATH %>');
+```
+
+Then replace:
+
+```js
+      var BK_STATIC_URL = '<%= process.env.BK_STATIC_URL %>'
+```
+
+with:
+
+```js
+      var BK_STATIC_URL = normalizeAssetBase('<%= process.env.BK_STATIC_URL %>', BK_SITE_PATH)
+      window.BK_SITE_PATH = BK_SITE_PATH
+      window.BK_STATIC_URL = BK_STATIC_URL
+      window.__loadAssetsUrl__ = function (src) {
+        return joinUrl(window.BK_STATIC_URL || '/', src);
+      }
+```
+
+- [ ] **Step 5: Fix project-id extraction and cookie path in `index.html`**
+
+Replace the production project id block:
+
+```js
+          var projectId =
+            document.location.pathname.match(/^\/codecc\/([\w.-_]+)\/?/)?.[1] ||
+            document.location.search.match(/projectId=([\w.-_]+)/)?.[1] || '';
+```
+
+with:
+
+```js
+          var sitePath = window.BK_SITE_PATH || '/';
+          var pathWithoutSitePath = document.location.pathname;
+          if (sitePath !== '/' && pathWithoutSitePath.indexOf(sitePath) === 0) {
+            pathWithoutSitePath = '/' + pathWithoutSitePath.slice(sitePath.length);
+          }
+          var projectId =
+            pathWithoutSitePath.match(/^\/codecc\/([\w._-]+)\/?/)?.[1] ||
+            document.location.search.match(/projectId=([\w._-]+)/)?.[1] || '';
+```
+
+Replace cookie path:
+
+```js
+              ';path=/';
+```
+
+with:
+
+```js
+              ';path=' +
+              (window.BK_SITE_PATH || '/');
+```
+
+- [ ] **Step 6: Fix iframe devops utility prefix handling**
+
+Replace:
+
+```js
+          var prefix = '__BK_CI_PUBLIC_PATH_PREFIX__' ? '__BK_CI_PUBLIC_PATH_PREFIX__' : DEVOPS_SITE_URL
+```
+
+with:
+
+```js
+          var ciPublicPathPrefix = '__BK_CI_PUBLIC_PATH_PREFIX__';
+          var prefix = ciPublicPathPrefix && ciPublicPathPrefix.indexOf('__') !== 0
+            ? ciPublicPathPrefix
+            : DEVOPS_SITE_URL;
+```
+
+- [ ] **Step 7: Verify build still completes**
+
+Run:
+
+```bash
+cd /Users/brooklin/project/github/bk-codecc/src/frontend/devops-codecc
+npm run build
+```
+
+Expected: build exits 0 and `dist/index.html` exists.
+
+- [ ] **Step 8: Commit Task 2**
+
+Run:
+
+```bash
+git add src/frontend/devops-codecc/static/webpack_public_path.js src/frontend/devops-codecc/index.html src/frontend/devops-codecc/src/main.js src/frontend/devops-codecc/.bk.production.env
+git commit -m "feat(frontend): inject runtime subpath settings"
+```
+
+Expected: commit succeeds.
+
+## Task 3: Configure Router Base and Login Callback
+
+**Files:**
+- Modify: `src/frontend/devops-codecc/src/router/index.js`
+- Modify: `src/frontend/devops-codecc/src/api/index.js`
+
+- [ ] **Step 1: Configure Vue Router base**
+
+Modify `src/frontend/devops-codecc/src/router/index.js`:
+
+```js
+const router = new VueRouter({
+  mode: 'history',
+  base: window.BK_SITE_PATH || '/',
+  routes,
+});
+```
+
+- [ ] **Step 2: Import static URL helper in API wrapper**
+
+In `src/frontend/devops-codecc/src/api/index.js`, add:
+
+```js
+import { withStaticUrl } from '@/utils/path';
+```
+
+Place it near the other local imports.
+
+- [ ] **Step 3: Use static prefix for login modal callback**
+
+Replace:
+
+```js
+        const successUrl = `${window.location.origin}/static/login_success.html`;
+```
+
+with:
+
+```js
+        const successUrl = `${window.location.origin}${withStaticUrl('/static/login_success.html')}`;
+```
+
+- [ ] **Step 4: Verify lint for touched files**
+
+Run:
+
+```bash
+cd /Users/brooklin/project/github/bk-codecc/src/frontend/devops-codecc
+npx eslint src/router/index.js src/api/index.js src/utils/path.js
+```
+
+Expected: exits 0. If the repo's eslint config reports pre-existing style issues outside these edits, fix only issues in the touched lines.
+
+- [ ] **Step 5: Commit Task 3**
+
+Run:
+
+```bash
+git add src/frontend/devops-codecc/src/router/index.js src/frontend/devops-codecc/src/api/index.js
+git commit -m "feat(frontend): apply site path to router and login callback"
+```
+
+Expected: commit succeeds.
+
+## Task 4: Audit and Fix CodeCC-Owned Manual Internal URLs
+
+**Files:**
+- Modify: `src/frontend/devops-codecc/src/views/paas/test/design-report.vue`
+- Modify additional files only when the audit proves they construct CodeCC-owned root URLs.
+
+- [ ] **Step 1: Run the manual URL audit**
+
+Run:
+
+```bash
+cd /Users/brooklin/project/github/bk-codecc
+rg -n "window\\.location\\.origin|location\\.origin|/codecc/|/static/login_success|router\\.resolve|\\$router\\.resolve" src/frontend/devops-codecc/src -g '*.js' -g '*.vue'
+```
+
+Expected: output lists candidate call sites. Classify each as one of:
+
+- CodeCC internal URL that needs `withSitePath`;
+- webpack/static URL that needs `withStaticUrl`;
+- external product URL that must stay unchanged;
+- router-resolved href that already includes `router.base`.
+
+- [ ] **Step 2: Fix PaaS design report internal URL**
+
+In `src/frontend/devops-codecc/src/views/paas/test/design-report.vue`, add:
+
+```js
+import { withSitePath } from '@/utils/path';
+```
+
+Replace:
+
+```js
+      const url = `${window.location.origin}/codecc/${row.projectId}/task/${row.taskId}/detail`;
+```
+
+with:
+
+```js
+      const url = `${window.location.origin}${withSitePath(`/codecc/${row.projectId}/task/${row.taskId}/detail`)}`;
+```
+
+- [ ] **Step 3: Fix any additional CodeCC-owned root URL from the audit**
+
+For each audited CodeCC internal URL with a literal `/codecc/...`, use this pattern:
+
+```js
+import { withSitePath } from '@/utils/path';
+
+const url = `${window.location.origin}${withSitePath('/codecc/demo/task/list')}`;
+```
+
+Do not apply this pattern to `window.DEVOPS_SITE_URL`, `window.STREAM_SITE_URL`, `window.PAAS_SERVICE_URL`, `window.PAAS_V3_URL`, `window.IWIKI_SITE_URL`, or IAM URLs.
+
+- [ ] **Step 4: Verify no unclassified root CodeCC URLs remain**
+
+Run:
+
+```bash
+cd /Users/brooklin/project/github/bk-codecc
+rg -n "window\\.location\\.origin.*\\/codecc/|location\\.origin.*\\/codecc/|`\\$\\{window\\.location\\.origin\\}/codecc/" src/frontend/devops-codecc/src -g '*.js' -g '*.vue'
+```
+
+Expected: no output.
+
+- [ ] **Step 5: Run lint for touched files**
+
+Run:
+
+```bash
+cd /Users/brooklin/project/github/bk-codecc/src/frontend/devops-codecc
+npx eslint src/views/paas/test/design-report.vue src/utils/path.js
+```
+
+Expected: exits 0.
+
+- [ ] **Step 6: Commit Task 4**
+
+Run:
+
+```bash
+git add src/frontend/devops-codecc/src/views/paas/test/design-report.vue
+git commit -m "feat(frontend): respect site path in internal urls"
+```
+
+If Step 3 touched additional files, include them in `git add`.
+
+Expected: commit succeeds.
+
+## Task 5: Add Deployment Variables
+
+**Files:**
+- Modify: `scripts/deploy-codecc/codecc.properties`
+- Modify: `docker-images/core/codecc/gateway/scripts/codecc.env`
+- Modify: `helm-charts/core/codecc/templates/gateway/deployment.yaml`
+
+- [ ] **Step 1: Add traditional deployment default**
+
+In `scripts/deploy-codecc/codecc.properties`, near `BK_PUBLIC_PATH_PREFIX`, add:
+
+```properties
+# BK_SITE_PATH 默认为 /，用于 CodeCC 前端 history 路由子路径。值必须为 / 或 /path/
+BK_SITE_PATH=/
+```
+
+- [ ] **Step 2: Add container env template**
+
+In `docker-images/core/codecc/gateway/scripts/codecc.env`, add:
+
+```env
+BK_SITE_PATH=$BK_SITE_PATH
+```
+
+Place it near the existing `BK_PUBLIC_PATH_PREFIX` or frontend URL variables.
+
+- [ ] **Step 3: Add Helm gateway environment variable**
+
+In `helm-charts/core/codecc/templates/gateway/deployment.yaml`, add:
+
+```yaml
+            - name: BK_SITE_PATH
+              value: {{ default "/" .Values.config.bkSitePath }}
+```
+
+Place it immediately before `BK_PUBLIC_PATH_PREFIX`.
+
+- [ ] **Step 4: Verify Helm template syntax**
+
+Run:
+
+```bash
+cd /Users/brooklin/project/github/bk-codecc/helm-charts/core/codecc
+helm template codecc . >/tmp/codecc-helm-render.yaml
+```
+
+Expected: exits 0 and `/tmp/codecc-helm-render.yaml` contains `name: BK_SITE_PATH`.
+
+- [ ] **Step 5: Commit Task 5**
+
+Run:
+
+```bash
+git add scripts/deploy-codecc/codecc.properties docker-images/core/codecc/gateway/scripts/codecc.env helm-charts/core/codecc/templates/gateway/deployment.yaml
+git commit -m "feat(deploy): add codecc frontend site path variable"
+```
+
+Expected: commit succeeds.
+
+## Task 6: Add Gateway Subpath Rewrite Before SPA Fallback
+
+**Files:**
+- Modify: `support-files/codecc/templates/core/gateway#core#vhosts#codecc.frontend.conf`
+
+- [ ] **Step 1: Strip site path in the root frontend location**
+
+Modify `location /` in `support-files/codecc/templates/core/gateway#core#vhosts#codecc.frontend.conf` from:
+
+```nginx
+  location / {
+    header_filter_by_lua_file 'conf/lua/cors_filter.lua';
+    add_header Cache-Control no-store;
+    index index.html index.htm;
+    try_files $uri @fallback;
+  }
+```
+
+to:
+
+```nginx
+  location / {
+    header_filter_by_lua_file 'conf/lua/cors_filter.lua';
+    add_header Cache-Control no-store;
+    index index.html index.htm;
+    rewrite ^__BK_SITE_PATH__(.*)$ /$1 break;
+    try_files $uri @fallback;
+  }
+```
+
+When `BK_SITE_PATH=/`, the rendered rewrite becomes `rewrite ^/(.*)$ /$1 break;`, which keeps root deployment behavior unchanged.
+
+- [ ] **Step 2: Strip site path in html fallback location**
+
+Modify `location ~* \.(html)$` from:
+
+```nginx
+  location ~* \.(html)$ {
+    header_filter_by_lua_file 'conf/lua/cors_filter.lua';
+    add_header Cache-Control no-store;
+    try_files $uri  @fallback;
+  # 匹配所有以 html结尾的请求
+  }
+```
+
+to:
+
+```nginx
+  location ~* \.(html)$ {
+    header_filter_by_lua_file 'conf/lua/cors_filter.lua';
+    add_header Cache-Control no-store;
+    rewrite ^__BK_SITE_PATH__(.*)$ /$1 break;
+    try_files $uri  @fallback;
+  # 匹配所有以 html结尾的请求
+  }
+```
+
+- [ ] **Step 3: Strip site path in static asset location**
+
+Modify `location ~* \.(js|css|ttf)$` from:
+
+```nginx
+  location ~* \.(js|css|ttf)$ {
+    header_filter_by_lua_file 'conf/lua/cors_filter.lua';
+    add_header Cache-Control max-age=2592000;
+    try_files $uri  @fallback;
+  # 匹配所有以 js,css或tff 结尾的请求
+  }
+```
+
+to:
+
+```nginx
+  location ~* \.(js|css|ttf)$ {
+    header_filter_by_lua_file 'conf/lua/cors_filter.lua';
+    add_header Cache-Control max-age=2592000;
+    rewrite ^__BK_SITE_PATH__(.*)$ /$1 break;
+    try_files $uri  @fallback;
+  # 匹配所有以 js,css或tff 结尾的请求
+  }
+```
+
+- [ ] **Step 4: Keep fallback rooted at built index**
+
+Confirm `location @fallback` still rewrites to `/index.html`:
+
+```nginx
+  location @fallback {
+    header_filter_by_lua_file 'conf/lua/cors_filter.lua';
+    add_header Cache-Control no-store;
+    rewrite .* /index.html break;
+  }
+```
+
+Expected: no change is needed in this block.
+
+- [ ] **Step 5: Verify nginx rendered config for root and subpath**
+
+Run the render command used by gateway startup with root values:
+
+```bash
+cd /Users/brooklin/project/github/bk-codecc
+tmpdir=$(mktemp -d)
+cp support-files/codecc/templates/core/gateway#core#vhosts#codecc.frontend.conf "$tmpdir/template.conf"
+BK_SITE_PATH=/ docker-images/core/codecc/gateway/scripts/render_tpl -u -p "$tmpdir" -m . "$tmpdir/template.conf"
+```
+
+Expected: rendered root config contains `rewrite ^/(.*)$ /$1 break;` inside frontend locations and no new `location ^~ /` block.
+
+Run again with subpath:
+
+```bash
+cd /Users/brooklin/project/github/bk-codecc
+tmpdir=$(mktemp -d)
+cp support-files/codecc/templates/core/gateway#core#vhosts#codecc.frontend.conf "$tmpdir/template.conf"
+BK_SITE_PATH=/codecc-demo/ docker-images/core/codecc/gateway/scripts/render_tpl -u -p "$tmpdir" -m . "$tmpdir/template.conf"
+```
+
+Expected: rendered subpath config contains `rewrite ^/codecc-demo/(.*)$ /$1 break;` inside frontend locations and fallback to `/index.html`.
+
+- [ ] **Step 6: Run nginx config syntax check when OpenResty is available**
+
+Run:
+
+```bash
+openresty -t -c /path/to/rendered/nginx.conf
+```
+
+Expected: `syntax is ok` and `test is successful`. If OpenResty is not installed locally, record that this check must run in the gateway image in Task 8.
+
+- [ ] **Step 7: Commit Task 6**
+
+Run:
+
+```bash
+git add support-files/codecc/templates/core/gateway#core#vhosts#codecc.frontend.conf
+git commit -m "feat(gateway): serve frontend under configured subpath"
+```
+
+Expected: commit succeeds.
+
+## Task 7: Add Build Output Verification
+
+**Files:**
+- Create: `src/frontend/devops-codecc/scripts/verify-subpath-dist.js`
+- Modify: `src/frontend/devops-codecc/package.json`
+
+- [ ] **Step 1: Add dist verifier script**
+
+Create `src/frontend/devops-codecc/scripts/verify-subpath-dist.js`:
+
+```js
+const fs = require('fs');
+const path = require('path');
+
+const distDir = path.resolve(__dirname, '../dist');
+const indexPath = path.join(distDir, 'index.html');
+const expectedSitePath = process.argv[2] || '/';
+const expectedStaticUrl = process.argv[3] || expectedSitePath;
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+if (!fs.existsSync(indexPath)) {
+  fail(`Missing ${indexPath}`);
+}
+
+const html = fs.readFileSync(indexPath, 'utf8');
+
+if (!html.includes(`BK_SITE_PATH`)) {
+  fail('dist/index.html does not define BK_SITE_PATH');
+}
+
+if (!html.includes(`BK_STATIC_URL`)) {
+  fail('dist/index.html does not define BK_STATIC_URL');
+}
+
+if (!html.includes(expectedSitePath)) {
+  fail(`dist/index.html does not contain expected site path ${expectedSitePath}`);
+}
+
+if (!html.includes(expectedStaticUrl)) {
+  fail(`dist/index.html does not contain expected static url ${expectedStaticUrl}`);
+}
+
+if (expectedStaticUrl !== '/' && html.includes('src="/js/')) {
+  fail('dist/index.html contains root-relative js entry in subpath mode');
+}
+
+console.log('subpath dist verification passed');
+```
+
+- [ ] **Step 2: Add package script**
+
+Modify `src/frontend/devops-codecc/package.json` scripts:
+
+```json
+"verify:subpath": "node ./scripts/verify-subpath-dist.js"
+```
+
+- [ ] **Step 3: Verify root build output**
+
+Run:
+
+```bash
+cd /Users/brooklin/project/github/bk-codecc/src/frontend/devops-codecc
+BK_SITE_PATH=/ BK_STATIC_URL=/ npm run build
+npm run verify:subpath -- / /
+```
+
+Expected: `subpath dist verification passed`.
+
+- [ ] **Step 4: Verify subpath build output**
+
+Run:
+
+```bash
+cd /Users/brooklin/project/github/bk-codecc/src/frontend/devops-codecc
+BK_SITE_PATH=/codecc-demo/ BK_STATIC_URL=/codecc-demo/ npm run build
+npm run verify:subpath -- /codecc-demo/ /codecc-demo/
+```
+
+Expected: `subpath dist verification passed`.
+
+- [ ] **Step 5: Commit Task 7**
+
+Run:
+
+```bash
+git add src/frontend/devops-codecc/scripts/verify-subpath-dist.js src/frontend/devops-codecc/package.json
+git commit -m "test(frontend): verify subpath build output"
+```
+
+Expected: commit succeeds.
+
+## Task 8: End-to-End Local Subpath Verification
+
+**Files:**
+- Create: `src/frontend/devops-codecc/scripts/serve-subpath-dist.js`
+- No production code changes unless verification exposes a defect.
+
+- [ ] **Step 1: Add local static server**
+
+Create `src/frontend/devops-codecc/scripts/serve-subpath-dist.js`:
+
+```js
+const express = require('express');
+const path = require('path');
+
+const app = express();
+const port = Number(process.env.PORT || 8099);
+const sitePath = process.env.BK_SITE_PATH || '/codecc-demo/';
+const normalizedSitePath = sitePath === '/' ? '/' : `/${sitePath.replace(/^\/+|\/+$/g, '')}/`;
+const distDir = path.resolve(__dirname, '../dist');
+
+app.use(normalizedSitePath, express.static(distDir));
+app.get(`${normalizedSitePath}*`, (req, res) => {
+  res.sendFile(path.join(distDir, 'index.html'));
+});
+
+app.listen(port, () => {
+  console.log(`Serving ${distDir} at http://127.0.0.1:${port}${normalizedSitePath}`);
+});
+```
+
+- [ ] **Step 2: Build subpath dist**
+
+Run:
+
+```bash
+cd /Users/brooklin/project/github/bk-codecc/src/frontend/devops-codecc
+BK_SITE_PATH=/codecc-demo/ BK_STATIC_URL=/codecc-demo/ npm run build
+```
+
+Expected: build exits 0.
+
+- [ ] **Step 3: Start the local server**
+
+Run:
+
+```bash
+cd /Users/brooklin/project/github/bk-codecc/src/frontend/devops-codecc
+BK_SITE_PATH=/codecc-demo/ PORT=8099 node scripts/serve-subpath-dist.js
+```
+
+Expected: server prints `Serving ... at http://127.0.0.1:8099/codecc-demo/` and stays running.
+
+- [ ] **Step 4: Browser smoke test deep links**
+
+Open these URLs in the in-app browser or Chrome:
+
+```text
+http://127.0.0.1:8099/codecc-demo/codecc/demo/task/list
+http://127.0.0.1:8099/codecc-demo/codecc/demo/task/123/detail
+http://127.0.0.1:8099/codecc-demo/403
+```
+
+Expected:
+
+- each page returns the frontend `index.html`;
+- JavaScript and CSS requests use `/codecc-demo/`;
+- async chunks use `/codecc-demo/`;
+- no request for `/js/...`, `/css/...`, or `/static/login_success.html` appears at the domain root.
+
+- [ ] **Step 5: Verify gateway image nginx syntax if local OpenResty was unavailable**
+
+Run the gateway image or a matching OpenResty environment and execute:
+
+```bash
+nginx -t
+```
+
+Expected: `syntax is ok` and `test is successful`.
+
+- [ ] **Step 6: Commit Task 8**
+
+Run:
+
+```bash
+git add src/frontend/devops-codecc/scripts/serve-subpath-dist.js
+git commit -m "test(frontend): add local subpath smoke server"
+```
+
+Expected: commit succeeds.
+
+## Task 9: Final Regression and Documentation
+
+**Files:**
+- Modify docs only if verification reveals deployment notes that should be preserved.
+
+- [ ] **Step 1: Run final frontend lint**
+
+Run:
+
+```bash
+cd /Users/brooklin/project/github/bk-codecc/src/frontend/devops-codecc
+npm run lint
+```
+
+Expected: exits 0.
+
+- [ ] **Step 2: Run final root build**
+
+Run:
+
+```bash
+cd /Users/brooklin/project/github/bk-codecc/src/frontend/devops-codecc
+BK_SITE_PATH=/ BK_STATIC_URL=/ npm run build
+npm run verify:subpath -- / /
+```
+
+Expected: both commands exit 0.
+
+- [ ] **Step 3: Run final subpath build**
+
+Run:
+
+```bash
+cd /Users/brooklin/project/github/bk-codecc/src/frontend/devops-codecc
+BK_SITE_PATH=/codecc-demo/ BK_STATIC_URL=/codecc-demo/ npm run build
+npm run verify:subpath -- /codecc-demo/ /codecc-demo/
+```
+
+Expected: both commands exit 0.
+
+- [ ] **Step 4: Check final diff**
+
+Run:
+
+```bash
+cd /Users/brooklin/project/github/bk-codecc
+git status --short
+git log --oneline -10
+```
+
+Expected:
+
+- worktree is clean after all task commits;
+- recent commits correspond to Tasks 1 through 8 plus this final task if docs were updated.
+
+- [ ] **Step 5: Summarize verification results**
+
+Prepare a final note with:
+
+```text
+Verified:
+- npm run lint
+- BK_SITE_PATH=/ BK_STATIC_URL=/ npm run build
+- npm run verify:subpath -- / /
+- BK_SITE_PATH=/codecc-demo/ BK_STATIC_URL=/codecc-demo/ npm run build
+- npm run verify:subpath -- /codecc-demo/ /codecc-demo/
+- local browser smoke under /codecc-demo/
+
+Not verified:
+- list any environment-only checks that could not run locally, such as gateway image nginx -t
+```
+
+- [ ] **Step 6: Commit final documentation if changed**
+
+If Step 5 produced a checked-in doc update, run:
+
+```bash
+git add docs/superpowers/specs/2026-05-13-codecc-subpath-design.md docs/superpowers/plans/2026-05-13-codecc-subpath-implementation.md
+git commit -m "docs: document codecc subpath verification"
+```
+
+Expected: commit succeeds. If no files changed, skip this step.
+
+## Self-Review Notes
+
+- Spec coverage: Tasks 1-4 cover frontend path variables, runtime public path, router base, login callback, internal URL audit, and cookie/project-id behavior. Tasks 5-6 cover deployment variables and gateway fallback. Tasks 7-9 cover build, local serving, and final verification.
+- Placeholder scan: no task intentionally leaves unresolved implementation placeholders. Audit-driven Task 4 allows additional files only when the command proves they are CodeCC-owned root URLs.
+- Type consistency: helper names are consistent across tasks: `normalizeBasePath`, `normalizeAssetBase`, `joinUrl`, `getSitePath`, `getStaticUrl`, `withSitePath`, and `withStaticUrl`.

From 8b0d22044b96515f562d2e3356b0d2b7324f98b8 Mon Sep 17 00:00:00 2001
From: brooklin <brooklin@tencent.com>
Date: Wed, 13 May 2026 17:56:00 +0800
Subject: [PATCH 3/3] =?UTF-8?q?feat:=20=E6=94=AF=E6=8C=81=20CodeCC=20?=
 =?UTF-8?q?=E5=89=8D=E7=AB=AF=E5=AD=90=E8=B7=AF=E5=BE=84=E9=83=A8=E7=BD=B2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

本次改造让 CodeCC 前端支持部署在 / 或任意配置的子路径下，并保持现有根路径访问兼容。

主要内容：

- 新增 BK_SITE_PATH、BK_STATIC_URL 运行时配置，并统一路由 base、静态资源 public path、登录回调、cookie path 与内部链接处理。

- 新增路径工具方法，修正 CodeCC 内部硬编码根路径跳转，支持绝对地址、协议相对地址和子路径拼接。

- 调整本地 dev server 配置，使 npm run dev 在 BK_SITE_PATH 子路径下也能正确加载入口、异步 chunk 和 history fallback。

- 部署配置、网关环境变量、Helm 模板和 nginx 前端模板补充 BK_SITE_PATH，支持网关按配置子路径回源到前端资源。

- 新增 build 产物校验脚本、路径工具校验脚本和本地 subpath 静态服务脚本，便于验证根路径与子路径两种模式。

验证：

- node ./scripts/verify-path-utils.js

- node -c ./scripts/verify-subpath-dist.js

- node -c ./scripts/serve-subpath-dist.js

- node -c ./bk.config.js
# Reviewed, transaction id: 80134
---
 .../core/codecc/gateway/scripts/codecc.env    |  3 +-
 .../codecc/templates/gateway/deployment.yaml  |  4 +-
 scripts/deploy-codecc/codecc.properties       |  2 +
 src/frontend/devops-codecc/.bk.production.env |  3 +-
 src/frontend/devops-codecc/bk.config.js       | 40 ++++++--
 src/frontend/devops-codecc/index.html         | 75 ++++++++++++++-
 src/frontend/devops-codecc/package.json       |  8 +-
 .../scripts/serve-subpath-dist.js             | 17 ++++
 .../scripts/verify-path-utils.js              | 66 +++++++++++++
 .../scripts/verify-subpath-dist.js            | 40 ++++++++
 src/frontend/devops-codecc/src/api/index.js   |  6 +-
 .../src/components/layout/layout-inner.vue    | 49 +++++++---
 src/frontend/devops-codecc/src/main.js        |  1 +
 .../devops-codecc/src/router/index.js         |  1 +
 src/frontend/devops-codecc/src/utils/path.js  | 92 +++++++++++++++++++
 .../src/views/checkerset/card.vue             |  7 +-
 .../src/views/defect/coverity-list.vue        |  5 +-
 .../devops-codecc/src/views/defect/detail.vue | 20 ++--
 .../src/views/paas/test/design-report.vue     |  4 +-
 .../static/webpack_public_path.js             |  1 +
 .../gateway#core#vhosts#codecc.frontend.conf  |  3 +
 21 files changed, 404 insertions(+), 43 deletions(-)
 create mode 100644 src/frontend/devops-codecc/scripts/serve-subpath-dist.js
 create mode 100644 src/frontend/devops-codecc/scripts/verify-path-utils.js
 create mode 100644 src/frontend/devops-codecc/scripts/verify-subpath-dist.js
 create mode 100644 src/frontend/devops-codecc/src/utils/path.js
 create mode 100644 src/frontend/devops-codecc/static/webpack_public_path.js

diff --git a/docker-images/core/codecc/gateway/scripts/codecc.env b/docker-images/core/codecc/gateway/scripts/codecc.env
index 6845dd87..da6820dd 100644
--- a/docker-images/core/codecc/gateway/scripts/codecc.env
+++ b/docker-images/core/codecc/gateway/scripts/codecc.env
@@ -24,8 +24,9 @@ BK_CODECC_PUBLIC_URL=$BK_CODECC_HOST
 BK_CODECC_GATEWAY_REGION_NAME=$BK_CODECC_GATEWAY_REGION_NAME
 BK_CI_PUBLIC_URL=$BK_CI_PUBLIC_URL
 BK_CI_FQDN=$BK_CI_FQDN
+BK_SITE_PATH=$BK_SITE_PATH
 BK_API_TENANT_HOST=$BK_API_TENANT_HOST
 BK_API_TENANT_BASE_URL=$BK_API_TENANT_BASE_URL
 BK_CODECC_ENABLE_MULTI_TENANT=$BK_CODECC_ENABLE_MULTI_TENANT
 BK_LOGIN_PATH=$BK_LOGIN_PATH
-BK_CI_JWT_RSA_PRIVATE_KEY=$BK_CI_JWT_RSA_PRIVATE_KEY
\ No newline at end of file
+BK_CI_JWT_RSA_PRIVATE_KEY=$BK_CI_JWT_RSA_PRIVATE_KEY
diff --git a/helm-charts/core/codecc/templates/gateway/deployment.yaml b/helm-charts/core/codecc/templates/gateway/deployment.yaml
index 40060fa8..c943ecbf 100644
--- a/helm-charts/core/codecc/templates/gateway/deployment.yaml
+++ b/helm-charts/core/codecc/templates/gateway/deployment.yaml
@@ -104,6 +104,8 @@ spec:
               value: {{ .Values.config.bkCodeccGatewayRegionName }}
             - name: BK_CI_FQDN
               value: {{ .Values.config.bkCiFqdn }}
+            - name: BK_SITE_PATH
+              value: {{ default "/" .Values.config.bkSitePath }}
             - name: BK_PUBLIC_PATH_PREFIX
               value: {{ .Values.config.bkPublicPathPrefix }}
             - name: BK_CI_PUBLIC_PATH_PREFIX
@@ -138,4 +140,4 @@ spec:
             - name: http
               containerPort: 80
               protocol: TCP
-{{- end }}
\ No newline at end of file
+{{- end }}
diff --git a/scripts/deploy-codecc/codecc.properties b/scripts/deploy-codecc/codecc.properties
index 9b95b648..1c0ad134 100644
--- a/scripts/deploy-codecc/codecc.properties
+++ b/scripts/deploy-codecc/codecc.properties
@@ -29,6 +29,8 @@ BK_REPO_GATEWAY_IP=127.0.0.1
 BK_CI_PUBLIC_PATH_PREFIX=
 # BK_PUBLIC_PATH_PREFIX 无默认值
 BK_PUBLIC_PATH_PREFIX=
+# BK_SITE_PATH 默认为 /，用于 CodeCC 前端 history 路由子路径。值必须为 / 或 /path/
+BK_SITE_PATH=/
 # BK_CODECC_FQDN默认为codecc.$BK_DOMAIN. 按需修改. 完全合格域名(即公网域名, 可解析为内网IP), 用于在CI集群外访问CI.
 BK_CODECC_FQDN=codecc.$BK_DOMAIN
 # BK_CODECC_HOME默认为$BK_HOME/codecc/. 无需修改. CI的安装目录.
diff --git a/src/frontend/devops-codecc/.bk.production.env b/src/frontend/devops-codecc/.bk.production.env
index b5b03a65..fd5f2ded 100644
--- a/src/frontend/devops-codecc/.bk.production.env
+++ b/src/frontend/devops-codecc/.bk.production.env
@@ -13,6 +13,7 @@ BK_IAM_URL_PREFIX = '__IAM_URL_PREFIX__'
 
 BK_AEGISID = '__AEGISID__'
 
+BK_SITE_PATH = '__BK_SITE_PATH__'
 BK_STATIC_URL = '__BK_PUBLIC_PATH_PREFIX__'
 BK_PRECI_URL = '__BK_PRECI_URL__'
 
@@ -21,4 +22,4 @@ BK_DEVOPS_SITE_TAI_URL = '__BK_CI_PUBLIC_TAI_URL__'
 BK_PAAS_SERVICE_TAI_URL = '__BK_PAAS_SERVICE_TAI_URL__'
 
 # 多租户基础组件接口地址
-BK_API_TENANT_BASE_URL = '__BK_API_TENANT_BASE_URL__'
\ No newline at end of file
+BK_API_TENANT_BASE_URL = '__BK_API_TENANT_BASE_URL__'
diff --git a/src/frontend/devops-codecc/bk.config.js b/src/frontend/devops-codecc/bk.config.js
index 15eb4248..802da245 100644
--- a/src/frontend/devops-codecc/bk.config.js
+++ b/src/frontend/devops-codecc/bk.config.js
@@ -1,10 +1,41 @@
 // const mockServer = require('./mock-server');
 // const fs = require('fs');
 
+function normalizeBasePath(value) {
+  if (!value) {
+    return '/';
+  }
+  const text = String(value).trim();
+  if (!text || text === '/') {
+    return '/';
+  }
+  return `/${text.replace(/^\/+|\/+$/g, '')}/`;
+}
+
+const isDevelopment = process.env.NODE_ENV === 'development';
+const devSitePath = normalizeBasePath(process.env.BK_SITE_PATH || '/');
+
+const devServerConfig = {
+  https: true,
+  client: {
+    overlay: false,
+  },
+};
+
+if (isDevelopment) {
+  devServerConfig.devMiddleware = {
+    publicPath: devSitePath,
+  };
+  devServerConfig.historyApiFallback = {
+    index: `${devSitePath}index.html`,
+    disableDotRule: true,
+  };
+}
+
 module.exports = {
   host: process.env.BK_APP_HOST,
   port: process.env.BK_APP_PORT,
-  // publicPath: process.env.BK_STATIC_URL,
+  ...(isDevelopment ? { publicPath: devSitePath } : {}),
   cache: true,
   open: false,
   replaceStatic: {
@@ -22,11 +53,6 @@ module.exports = {
 
   // webpack config 配置
   configureWebpack: {
-    devServer: {
-      https: true,
-      client: {
-        overlay: false,
-      },
-    },
+    devServer: devServerConfig,
   },
 };
diff --git a/src/frontend/devops-codecc/index.html b/src/frontend/devops-codecc/index.html
index 5f9b823c..22797088 100644
--- a/src/frontend/devops-codecc/index.html
+++ b/src/frontend/devops-codecc/index.html
@@ -16,6 +16,57 @@
   <body>
     <div id="app"></div>
     <script>
+      function normalizeBasePath(value) {
+        var path = (value || '').trim();
+        if (!path || path.indexOf('__') === 0) {
+          return '/';
+        }
+        if (path.charAt(0) !== '/') {
+          path = '/' + path;
+        }
+        path = path.replace(/\/+/g, '/');
+        if (path.charAt(path.length - 1) !== '/') {
+          path += '/';
+        }
+        return path;
+      }
+
+      function normalizeAssetBase(value, fallback) {
+        var base = (value || '').trim();
+        if (!base || base.indexOf('__') === 0) {
+          return normalizeBasePath(fallback);
+        }
+        if (/^(https?:)?\/\//.test(base)) {
+          return base.charAt(base.length - 1) === '/' ? base : base + '/';
+        }
+        return normalizeBasePath(base);
+      }
+
+      function joinUrl(base, path) {
+        var baseValue = String(base || '/');
+        var pathValue = String(path || '');
+        if (/^(https?:)?\/\//.test(pathValue)) {
+          return pathValue;
+        }
+        if (/^https?:\/\//.test(baseValue)) {
+          var url = new URL(baseValue);
+          url.pathname = [url.pathname, pathValue].join('/').replace(/\/+/g, '/');
+          return url.toString().replace(/\/$/, pathValue ? '' : '/');
+        }
+        if (baseValue.indexOf('//') === 0) {
+          return [baseValue.replace(/\/+$/, ''), pathValue.replace(/^\/+/, '')]
+            .filter(function (item) { return item !== ''; })
+            .join('/');
+        }
+        var startsWithRoot = baseValue.indexOf('/') === 0;
+        var joined = [baseValue, pathValue]
+          .filter(function (item) { return item !== ''; })
+          .join('/')
+          .replace(/\/+/g, '/');
+        return startsWithRoot ? '/' + joined.replace(/^\/+/, '') : joined;
+      }
+
+      var BK_SITE_PATH = normalizeBasePath('<%= process.env.BK_SITE_PATH %>');
       var PAAS_SERVICE_URL = '<%= process.env.BK_PAAS_SERVICE_URL %>';
       var AJAX_URL_PREFIX =
         '<%= process.env.NODE_ENV %>' === 'development'
@@ -48,7 +99,12 @@
       // aegis监控
       // var AEGISID = '<%= process.env.BK_AEGISID %>';
 
-      var BK_STATIC_URL = '<%= process.env.BK_STATIC_URL %>'
+      var BK_STATIC_URL = normalizeAssetBase('<%= process.env.BK_STATIC_URL %>', BK_SITE_PATH)
+      window.BK_SITE_PATH = BK_SITE_PATH
+      window.BK_STATIC_URL = BK_STATIC_URL
+      window.__loadAssetsUrl__ = function (src) {
+        return joinUrl(window.BK_STATIC_URL || '/', src);
+      }
       var IS_ENV_TAI = Boolean(location.host === '<%= process.env.BK_CODECC_HOST_TAI_URL %>')
 
       // 太湖环境
@@ -62,16 +118,24 @@
       (function () {
         if (window.self !== window.top) {
           // iframe嵌入
-          var prefix = '__BK_CI_PUBLIC_PATH_PREFIX__' ? '__BK_CI_PUBLIC_PATH_PREFIX__' : DEVOPS_SITE_URL
+          var ciPublicPathPrefix = '__BK_CI_PUBLIC_PATH_PREFIX__';
+          var prefix = ciPublicPathPrefix && ciPublicPathPrefix.indexOf('__') !== 0
+            ? ciPublicPathPrefix
+            : DEVOPS_SITE_URL;
           var script = document.createElement('script');
           script.type = 'text/javascript';
           script.src = prefix + '/console/static/devops-utils.js';
           document.getElementsByTagName('head')[0].appendChild(script);
         }
         if ('<%= process.env.NODE_ENV %>' !== 'development') {
+          var sitePath = window.BK_SITE_PATH || '/';
+          var pathWithoutSitePath = document.location.pathname;
+          if (sitePath !== '/' && pathWithoutSitePath.indexOf(sitePath) === 0) {
+            pathWithoutSitePath = '/' + pathWithoutSitePath.slice(sitePath.length);
+          }
           var projectId =
-            document.location.pathname.match(/^\/codecc\/([\w.-_]+)\/?/)?.[1] ||
-            document.location.search.match(/projectId=([\w.-_]+)/)?.[1] || '';
+            pathWithoutSitePath.match(/^\/codecc\/([\w._-]+)\/?/)?.[1] ||
+            document.location.search.match(/projectId=([\w._-]+)/)?.[1] || '';
           var projectIdInCookie = document.cookie.replace(
             /(?:(?:^|.*;\s*)X-DEVOPS-PROJECT-ID\s*\=\s*([^;]*).*$)|^.*$/,
             '$1'
@@ -82,7 +146,8 @@
               projectId +
               ';domain=' +
               location.host +
-              ';path=/';
+              ';path=' +
+              (window.BK_SITE_PATH || '/');
             document.location.reload();
           }
         }
diff --git a/src/frontend/devops-codecc/package.json b/src/frontend/devops-codecc/package.json
index 248337a6..0132f014 100644
--- a/src/frontend/devops-codecc/package.json
+++ b/src/frontend/devops-codecc/package.json
@@ -7,6 +7,7 @@
     "dev": "bk-cli-service-webpack dev",
     "build": "bk-cli-service-webpack build",
     "build:stag": "bk-cli-service-webpack build --mode stag",
+    "verify:subpath": "node ./scripts/verify-subpath-dist.js",
     "server": "node ./paas-server/index.js",
     "lint": "eslint --ext .js,.vue ./src",
     "lint:fix": "eslint --fix --ext .js,.vue ./src",
@@ -19,14 +20,15 @@
   "dependencies": {
     "@blueking/bk-user-display-name": "^1.0.2",
     "@blueking/bk-user-selector": "^0.1.1",
+    "@blueking/bkui-library": "^0.0.0-beta.6",
     "@blueking/log": "^2.0.14",
     "@blueking/login-modal": "^1.0.5",
-    "aegis-web-sdk": "^1.24.18",
-    "babel-plugin-import-bk-magic-vue": "latest",
-    "bk-magic-vue": "2.5.10-beta.13",
     "@vue/composition-api": "^1.7.1",
+    "aegis-web-sdk": "^1.24.18",
     "art-template": "^4.13.2",
     "axios": "^0.30.0",
+    "babel-plugin-import-bk-magic-vue": "latest",
+    "bk-magic-vue": "2.5.10-beta.13",
     "bk-permission": "^0.1.7",
     "brace": "^0.10.0",
     "codemirror": "^5.45.0",
diff --git a/src/frontend/devops-codecc/scripts/serve-subpath-dist.js b/src/frontend/devops-codecc/scripts/serve-subpath-dist.js
new file mode 100644
index 00000000..a2ae7bae
--- /dev/null
+++ b/src/frontend/devops-codecc/scripts/serve-subpath-dist.js
@@ -0,0 +1,17 @@
+const express = require('express');
+const path = require('path');
+
+const app = express();
+const port = Number(process.env.PORT || 8099);
+const sitePath = process.env.BK_SITE_PATH || '/codecc-demo/';
+const normalizedSitePath = sitePath === '/' ? '/' : `/${sitePath.replace(/^\/+|\/+$/g, '')}/`;
+const distDir = path.resolve(__dirname, '../dist');
+
+app.use(normalizedSitePath, express.static(distDir));
+app.get(`${normalizedSitePath}*`, (req, res) => {
+  res.sendFile(path.join(distDir, 'index.html'));
+});
+
+app.listen(port, () => {
+  console.log(`Serving ${distDir} at http://127.0.0.1:${port}${normalizedSitePath}`);
+});
diff --git a/src/frontend/devops-codecc/scripts/verify-path-utils.js b/src/frontend/devops-codecc/scripts/verify-path-utils.js
new file mode 100644
index 00000000..66ccdcd3
--- /dev/null
+++ b/src/frontend/devops-codecc/scripts/verify-path-utils.js
@@ -0,0 +1,66 @@
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const vm = require('vm');
+
+const sourcePath = path.resolve(__dirname, '../src/utils/path.js');
+const source = fs.readFileSync(sourcePath, 'utf8');
+const transformedSource = source
+  .replace(/export function /g, 'function ')
+  .concat('\nmodule.exports = { normalizeBasePath, normalizeAssetBase, joinUrl, getSitePath, getStaticUrl, withSitePath, withStaticUrl };');
+
+const sandbox = {
+  module: { exports: {} },
+  exports: {},
+  window: {},
+  URL,
+};
+
+vm.runInNewContext(transformedSource, sandbox, { filename: sourcePath });
+
+const {
+  normalizeBasePath,
+  normalizeAssetBase,
+  joinUrl,
+  getSitePath,
+  getStaticUrl,
+  withSitePath,
+  withStaticUrl,
+} = sandbox.module.exports;
+
+assert.strictEqual(normalizeBasePath(), '/');
+assert.strictEqual(normalizeBasePath(''), '/');
+assert.strictEqual(normalizeBasePath('/'), '/');
+assert.strictEqual(normalizeBasePath('codecc'), '/codecc/');
+assert.strictEqual(normalizeBasePath('/codecc'), '/codecc/');
+assert.strictEqual(normalizeBasePath('codecc/'), '/codecc/');
+assert.strictEqual(normalizeBasePath('/bk/codecc/'), '/bk/codecc/');
+assert.strictEqual(normalizeAssetBase('https://cdn.example.com/codecc'), 'https://cdn.example.com/codecc/');
+assert.strictEqual(normalizeAssetBase('//cdn.example.com/codecc'), '//cdn.example.com/codecc/');
+
+assert.strictEqual(joinUrl('/codecc-demo/', '/static/login_success.html'), '/codecc-demo/static/login_success.html');
+assert.strictEqual(joinUrl('/', '/static/login_success.html'), '/static/login_success.html');
+assert.strictEqual(joinUrl('https://example.com/codecc/', '/static/a.js'), 'https://example.com/codecc/static/a.js');
+assert.strictEqual(joinUrl('/codecc-demo/', 'https://cdn.example.com/a.js'), 'https://cdn.example.com/a.js');
+assert.strictEqual(joinUrl('/codecc-demo/', '//cdn.example.com/a.js'), '//cdn.example.com/a.js');
+
+sandbox.window.BK_SITE_PATH = '/codecc-demo/';
+sandbox.window.BK_STATIC_URL = '/static-prefix/';
+delete sandbox.window.BK_STATIC_URL;
+assert.strictEqual(getStaticUrl(), '/codecc-demo/');
+
+sandbox.window.BK_STATIC_URL = '';
+assert.strictEqual(getSitePath(), '/codecc-demo/');
+assert.strictEqual(getStaticUrl(), '/codecc-demo/');
+assert.strictEqual(withSitePath('/codecc/demo/task/list'), '/codecc-demo/codecc/demo/task/list');
+assert.strictEqual(withStaticUrl('/static/login_success.html'), '/codecc-demo/static/login_success.html');
+
+sandbox.window.BK_STATIC_URL = '/static-prefix/';
+assert.strictEqual(getStaticUrl(), '/static-prefix/');
+assert.strictEqual(withStaticUrl('/static/login_success.html'), '/static-prefix/static/login_success.html');
+
+sandbox.window.BK_STATIC_URL = 'https://cdn.example.com/codecc';
+assert.strictEqual(getStaticUrl(), 'https://cdn.example.com/codecc/');
+assert.strictEqual(withStaticUrl('/static/login_success.html'), 'https://cdn.example.com/codecc/static/login_success.html');
+
+console.log('path utils verifier passed');
diff --git a/src/frontend/devops-codecc/scripts/verify-subpath-dist.js b/src/frontend/devops-codecc/scripts/verify-subpath-dist.js
new file mode 100644
index 00000000..4a05432f
--- /dev/null
+++ b/src/frontend/devops-codecc/scripts/verify-subpath-dist.js
@@ -0,0 +1,40 @@
+const fs = require('fs');
+const path = require('path');
+
+const distDir = path.resolve(__dirname, '../dist');
+const indexPath = path.join(distDir, 'index.html');
+const expectedSitePath = process.argv[2] || '/';
+const expectedStaticUrl = process.argv[3] || expectedSitePath;
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+if (!fs.existsSync(indexPath)) {
+  fail(`Missing ${indexPath}`);
+}
+
+const html = fs.readFileSync(indexPath, 'utf8');
+
+if (!html.includes('BK_SITE_PATH')) {
+  fail('dist/index.html does not define BK_SITE_PATH');
+}
+
+if (!html.includes('BK_STATIC_URL')) {
+  fail('dist/index.html does not define BK_STATIC_URL');
+}
+
+if (!html.includes(expectedSitePath)) {
+  fail(`dist/index.html does not contain expected site path ${expectedSitePath}`);
+}
+
+if (!html.includes(expectedStaticUrl)) {
+  fail(`dist/index.html does not contain expected static url ${expectedStaticUrl}`);
+}
+
+if (expectedStaticUrl !== '/' && html.includes('src="/js/')) {
+  fail('dist/index.html contains root-relative js entry in subpath mode');
+}
+
+console.log('subpath dist verification passed');
diff --git a/src/frontend/devops-codecc/src/api/index.js b/src/frontend/devops-codecc/src/api/index.js
index aaffcd95..14319d68 100755
--- a/src/frontend/devops-codecc/src/api/index.js
+++ b/src/frontend/devops-codecc/src/api/index.js
@@ -13,6 +13,7 @@ import { bus } from '../common/bus';
 import { messageError } from '@/common/bkmagic';
 import store from '@/store';
 import I18n from '@/i18n';
+import { withStaticUrl } from '@/utils/path';
 // import router from '@/router'
 import { showLoginModal } from '@blueking/login-modal';
 
@@ -212,7 +213,10 @@ function handleReject(error, config) {
         }/?c_url=${encodeURIComponent(window.location.href)}`;
       } else {
         // 登录成功之后的回调地址，用于执行关闭登录窗口或刷新父窗口页面等动作
-        const successUrl = `${window.location.origin}/static/login_success.html`;
+        const staticSuccessUrl = withStaticUrl('/static/login_success.html');
+        const successUrl = /^(https?:)?\/\//.test(staticSuccessUrl)
+          ? staticSuccessUrl
+          : `${window.location.origin}${staticSuccessUrl}`;
 
         // 系统的登录页地址
         const siteLoginUrl = window.PAAS_SERVICE_URL || '';
diff --git a/src/frontend/devops-codecc/src/components/layout/layout-inner.vue b/src/frontend/devops-codecc/src/components/layout/layout-inner.vue
index 607a04ec..f2583421 100644
--- a/src/frontend/devops-codecc/src/components/layout/layout-inner.vue
+++ b/src/frontend/devops-codecc/src/components/layout/layout-inner.vue
@@ -470,60 +470,65 @@ export default {
       }
       const params = { ...this.$route.params, toolId: toolName };
       // delete routeParams.toolId
+      // 注意：href 用于 <a> 标签显示（需包含 router base，如 /codecc-demo/）；
+      // to 用于 router.push（不能包含 base，否则会被再次拼接导致 base 重复）。
+      const resolveItem = location => ({
+        to: location,
+        href: this.$router.resolve(location).href,
+      });
       const menuBase = [
         {
           id: 'task-detail',
           name: this.$t('总览'),
           routeName: 'task-detail',
           icon: 'icon-apps',
-          href: this.$router.resolve({
+          ...resolveItem({
             name: 'task-detail',
             params: routeParams,
             query: { buildNum: 'latest' },
-          }).href,
+          }),
         },
         {
           id: 'task-settings',
           name: this.$t('设置'),
           routeName: 'task-settings',
           icon: 'codecc-icon icon-setting',
-          group: true,
-          href: this.$router.resolve({
-            name: 'task-settings',
+          ...resolveItem({
+            name: 'task-settings-code',
             params: routeParams,
-          }).href,
+          }),
         },
         {
           id: 'defect',
           name: this.$t('代码问题'),
           routeName: 'defect-lint',
           icon: 'icon-order',
-          href: this.$router.resolve({
+          ...resolveItem({
             name: `defect-${this.dimension.toLocaleLowerCase()}-list`,
             params,
             query: { dimension: this.dimension },
-          }).href,
+          }),
         },
         {
           id: 'ccn',
           name: this.$t('圈复杂度'),
           routeName: 'defect-ccn',
           icon: 'codecc-icon icon-complexity',
-          href: this.$router.resolve({ name: 'defect-ccn-list', params }).href,
+          ...resolveItem({ name: 'defect-ccn-list', params }),
         },
         {
           id: 'dupc',
           name: this.$t('重复率'),
           routeName: 'defect-dupc',
           icon: 'codecc-icon icon-repeat-rate',
-          href: this.$router.resolve({ name: 'defect-dupc-list', params }).href,
+          ...resolveItem({ name: 'defect-dupc-list', params }),
         },
         {
           id: 'cloc',
           name: this.$t('代码统计'),
           routeName: 'defect-cloc',
           icon: 'codecc-icon icon-statistics',
-          href: this.$router.resolve({ name: 'defect-cloc-list', params }).href,
+          ...resolveItem({ name: 'defect-cloc-list', params }),
         },
       ];
       const scaMenusConfig = {
@@ -531,7 +536,7 @@ export default {
         name: this.$t('软件成分'),
         routeName: 'defect-sca',
         icon: 'codecc-icon icon-software-components',
-        href: this.$router.resolve({ name: 'defect-sca-pkg-list', params }).href,
+        ...resolveItem({ name: 'defect-sca-pkg-list', params }),
       };
       // 若scaList不为空，则展示软件成分
       if (this.scaList.length > 0) {
@@ -706,8 +711,24 @@ export default {
       });
     },
     handleMenuSelect(id, item) {
-      if (item.href !== this.$route.path) {
-        this.$router.push(item.href);
+      // bk-navigation-menu 的 select 事件 item 是子组件实例，不是 menus 里的配置对象，
+      // 因此需要按 id 在 menus（及其 children）中查找对应配置。
+      const findMenuConfig = (list) => {
+        for (const cfg of list) {
+          if (cfg.id === id) return cfg;
+          if (cfg.children) {
+            const hit = findMenuConfig(cfg.children);
+            if (hit) return hit;
+          }
+        }
+        return null;
+      };
+      const config = findMenuConfig(this.menus);
+      if (!config || !config.to) return;
+      // 使用未拼接 base 的 location 对象进行跳转，避免 router.push 时 base 被重复拼接
+      const resolved = this.$router.resolve(config.to);
+      if (resolved.route.fullPath !== this.$route.fullPath) {
+        this.$router.push(config.to);
       }
     },
     openSlider() {
diff --git a/src/frontend/devops-codecc/src/main.js b/src/frontend/devops-codecc/src/main.js
index 6c605959..ed3fd033 100755
--- a/src/frontend/devops-codecc/src/main.js
+++ b/src/frontend/devops-codecc/src/main.js
@@ -3,6 +3,7 @@
  * @author blueking
  */
 
+import '../static/webpack_public_path';
 import Vue from 'vue';
 
 import router from './router';
diff --git a/src/frontend/devops-codecc/src/router/index.js b/src/frontend/devops-codecc/src/router/index.js
index 3cb2a98d..bd866e84 100755
--- a/src/frontend/devops-codecc/src/router/index.js
+++ b/src/frontend/devops-codecc/src/router/index.js
@@ -84,6 +84,7 @@ const routes = rootRoutes.concat(
 
 const router = new VueRouter({
   mode: 'history',
+  base: window.BK_SITE_PATH || '/',
   routes,
 });
 
diff --git a/src/frontend/devops-codecc/src/utils/path.js b/src/frontend/devops-codecc/src/utils/path.js
new file mode 100644
index 00000000..8822451b
--- /dev/null
+++ b/src/frontend/devops-codecc/src/utils/path.js
@@ -0,0 +1,92 @@
+const ABSOLUTE_URL_REGEXP = /^(?:https?:)?\/\//i;
+const HTTP_URL_REGEXP = /^https?:\/\//i;
+
+function getWindowValue(key) {
+  if (typeof window === 'undefined') {
+    return undefined;
+  }
+
+  return window[key];
+}
+
+function ensureTrailingSlash(value) {
+  return value.endsWith('/') ? value : `${value}/`;
+}
+
+function stripLeadingSlashes(value) {
+  return value.replace(/^\/+/, '');
+}
+
+function stripTrailingSlashes(value) {
+  return value.replace(/\/+$/, '');
+}
+
+function isAbsoluteUrl(value) {
+  return ABSOLUTE_URL_REGEXP.test(value);
+}
+
+function isHttpUrl(value) {
+  return HTTP_URL_REGEXP.test(value);
+}
+
+function joinPathname(basePath, path) {
+  return `${stripTrailingSlashes(basePath)}/${stripLeadingSlashes(path)}`;
+}
+
+export function normalizeBasePath(value = '/') {
+  const normalizedValue = String(value || '').trim();
+  const basePath = normalizedValue.replace(/^\/+|\/+$/g, '');
+
+  return basePath ? `/${basePath}/` : '/';
+}
+
+export function normalizeAssetBase(value, fallback = '/') {
+  const normalizedValue = value == null ? '' : String(value).trim();
+  const assetBase = normalizedValue || fallback;
+
+  if (isAbsoluteUrl(String(assetBase))) {
+    return ensureTrailingSlash(String(assetBase));
+  }
+
+  return normalizeBasePath(assetBase);
+}
+
+export function joinUrl(base = '/', path = '') {
+  const urlPath = String(path || '');
+
+  if (isAbsoluteUrl(urlPath)) {
+    return urlPath;
+  }
+
+  const normalizedBase = normalizeAssetBase(base);
+  const normalizedPath = stripLeadingSlashes(urlPath);
+
+  if (!normalizedPath) {
+    return normalizedBase;
+  }
+
+  if (isHttpUrl(normalizedBase)) {
+    const url = new URL(normalizedBase);
+    url.pathname = joinPathname(url.pathname, normalizedPath);
+
+    return url.toString();
+  }
+
+  return joinPathname(normalizedBase, normalizedPath);
+}
+
+export function getSitePath() {
+  return normalizeBasePath(getWindowValue('BK_SITE_PATH') || '/');
+}
+
+export function getStaticUrl() {
+  return normalizeAssetBase(getWindowValue('BK_STATIC_URL'), getSitePath());
+}
+
+export function withSitePath(path) {
+  return joinUrl(getSitePath(), path);
+}
+
+export function withStaticUrl(path) {
+  return joinUrl(getStaticUrl(), path);
+}
diff --git a/src/frontend/devops-codecc/src/views/checkerset/card.vue b/src/frontend/devops-codecc/src/views/checkerset/card.vue
index cc6ad261..81c5b525 100644
--- a/src/frontend/devops-codecc/src/views/checkerset/card.vue
+++ b/src/frontend/devops-codecc/src/views/checkerset/card.vue
@@ -239,6 +239,7 @@
 <script>
 import { mapState } from 'vuex';
 import { language } from '../../i18n';
+import { withSitePath } from '@/utils/path';
 
 export default {
   props: {
@@ -550,11 +551,13 @@ export default {
     },
     goToTaskDetailUrl(taskId) {
       let prefix = `${location.protocol}//${location.host}`;
+      let path = withSitePath(`/codecc/${this.projectId}/task/${taskId}/detail`);
       if (window.self !== window.top) {
         prefix = `${window.DEVOPS_SITE_URL}/console`;
+        path = `/codecc/${this.projectId}/task/${taskId}/detail`;
       }
-      return `${prefix}/codecc/${this.projectId}/task/${taskId}/detail`
-    }
+      return `${prefix}${path}`;
+    },
   },
 };
 </script>
diff --git a/src/frontend/devops-codecc/src/views/defect/coverity-list.vue b/src/frontend/devops-codecc/src/views/defect/coverity-list.vue
index 6f3fdcec..ffa10c5b 100755
--- a/src/frontend/devops-codecc/src/views/defect/coverity-list.vue
+++ b/src/frontend/devops-codecc/src/views/defect/coverity-list.vue
@@ -1481,6 +1481,7 @@ import { export_json_to_excel } from '@/vendor/export2Excel';
 import DefectBlock from './defect-block/defect-block';
 import OperateDialog from '@/components/operate-dialog';
 import UserSelector from '@/components/user-selector/index.vue';
+import { withSitePath } from '@/utils/path';
 
 // 搜索过滤项缓存
 const COVERITY_SEARCH_OPTION_CACHE = 'search_option_columns_coverity';
@@ -2972,10 +2973,12 @@ export default {
       const { projectId, taskId } = this.$route.params;
       const { toolName, entityId, status } = this.currentFile;
       let prefix = `${location.protocol}//${location.host}`;
+      let path = withSitePath(`/codecc/${projectId}/task/${taskId}/defect/compile/${toolName}/list`);
       if (window.self !== window.top) {
         prefix = `${location.protocol}${window.DEVOPS_SITE_URL}/console`;
+        path = `/codecc/${projectId}/task/${taskId}/defect/compile/${toolName}/list`;
       }
-      const url = `${prefix}/codecc/${projectId}/task/${taskId}/defect/compile/${toolName}/list
+      const url = `${prefix}${path}
 ?entityId=${entityId}&status=${status}`;
       const input = document.createElement('input');
       document.body.appendChild(input);
diff --git a/src/frontend/devops-codecc/src/views/defect/detail.vue b/src/frontend/devops-codecc/src/views/defect/detail.vue
index 38666028..0d1e110f 100644
--- a/src/frontend/devops-codecc/src/views/defect/detail.vue
+++ b/src/frontend/devops-codecc/src/views/defect/detail.vue
@@ -586,6 +586,7 @@ import AiSuggestion from './ai-suggestion.vue';
 import CheckerDetail from './checker-detail.vue';
 import DEPLOY_ENV from '@/constants/env';
 import ignoreApprovalIng from '@/images/ignore-approval-ing.svg';
+import { withSitePath } from '@/utils/path';
 
 export default {
   components: {
@@ -1615,18 +1616,25 @@ export default {
     shareDefect() {
       const { projectId, taskId } = this.$route.params;
       const { toolName, entityId, status } = this.currentFile;
-      let prefix = `${location.host}`;
+      let url = `${location.host}${withSitePath(`/codecc/${projectId}/task/${taskId}/defect/lint/${toolName}/list`)}
+?entityId=${entityId}&status=${status}`;
       if (window.self !== window.top) {
-        prefix = `${window.DEVOPS_SITE_URL}/console`;
-      }
-      let url = `${prefix}/codecc/${projectId}/task/${taskId}/defect/lint/${toolName}/list
+        url = `${window.DEVOPS_SITE_URL}/console/codecc/${projectId}/task/${taskId}/defect/lint/${toolName}/list
 ?entityId=${entityId}&status=${status}`;
+      }
       if (this.isProjectDefect) {
-        url = `${prefix}/codecc/${projectId}/defect/list
+        url = `${location.host}${withSitePath(`/codecc/${projectId}/defect/list`)}
 ?entityId=${entityId}&status=${status}`;
+        if (window.self !== window.top) {
+          url = `${window.DEVOPS_SITE_URL}/console/codecc/${projectId}/defect/list
+?entityId=${entityId}&status=${status}`;
+        }
       }
       if (this.isPaas) {
-        url = `${prefix}/paas/ignored/${toolName}/list?entityId=${entityId}`;
+        url = `${location.host}${withSitePath(`/paas/ignored/${toolName}/list`)}?entityId=${entityId}`;
+        if (window.self !== window.top) {
+          url = `${window.DEVOPS_SITE_URL}/console/paas/ignored/${toolName}/list?entityId=${entityId}`;
+        }
       }
       const input = document.createElement('input');
       document.body.appendChild(input);
diff --git a/src/frontend/devops-codecc/src/views/paas/test/design-report.vue b/src/frontend/devops-codecc/src/views/paas/test/design-report.vue
index 03d2b51a..7c678685 100644
--- a/src/frontend/devops-codecc/src/views/paas/test/design-report.vue
+++ b/src/frontend/devops-codecc/src/views/paas/test/design-report.vue
@@ -168,6 +168,7 @@
 import { format } from 'date-fns';
 // eslint-disable-next-line
 import { export_json_to_excel } from '@/vendor/export2Excel';
+import { withSitePath } from '@/utils/path';
 
 export default {
   name: 'DesignReport',
@@ -393,7 +394,8 @@ export default {
       this.queryTestReportDetailList(searchParams);
     },
     openTaskOverview(row) {
-      const url = `${window.location.origin}/codecc/${row.projectId}/task/${row.taskId}/detail`;
+      const taskPath = withSitePath(`/codecc/${row.projectId}/task/${row.taskId}/detail`);
+      const url = `${window.location.origin}${taskPath}`;
       window.open(url, '_blank');
     },
     openGitRepo(row) {
diff --git a/src/frontend/devops-codecc/static/webpack_public_path.js b/src/frontend/devops-codecc/static/webpack_public_path.js
new file mode 100644
index 00000000..ccb8bef3
--- /dev/null
+++ b/src/frontend/devops-codecc/static/webpack_public_path.js
@@ -0,0 +1 @@
+__webpack_public_path__ = window.BK_STATIC_URL || '/';
diff --git a/support-files/codecc/templates/core/gateway#core#vhosts#codecc.frontend.conf b/support-files/codecc/templates/core/gateway#core#vhosts#codecc.frontend.conf
index 61c86af0..42083715 100644
--- a/support-files/codecc/templates/core/gateway#core#vhosts#codecc.frontend.conf
+++ b/support-files/codecc/templates/core/gateway#core#vhosts#codecc.frontend.conf
@@ -12,12 +12,14 @@
     header_filter_by_lua_file 'conf/lua/cors_filter.lua';
     add_header Cache-Control no-store;
     index index.html index.htm;
+    rewrite ^__BK_SITE_PATH__(.*)$ /$1 break;
     try_files $uri @fallback;
   }
 
   location ~* \.(html)$ {
     header_filter_by_lua_file 'conf/lua/cors_filter.lua';
     add_header Cache-Control no-store;
+    rewrite ^__BK_SITE_PATH__(.*)$ /$1 break;
     try_files $uri  @fallback;
   # 匹配所有以 html结尾的请求
   }
@@ -25,6 +27,7 @@
   location ~* \.(js|css|ttf)$ {
     header_filter_by_lua_file 'conf/lua/cors_filter.lua';
     add_header Cache-Control max-age=2592000;
+    rewrite ^__BK_SITE_PATH__(.*)$ /$1 break;
     try_files $uri  @fallback;
   # 匹配所有以 js,css或tff 结尾的请求
   }