NickWilde18 · NickWilde18 · May 7, 2026 · May 7, 2026 · May 7, 2026 · May 7, 2026
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
@@ -0,0 +1,76 @@
+name: Build & push docker image
+
+# 推 fork/main 时自动 build + push docker.io/nickwilde18/pkgsitex 单 image
+# 含 worker / frontend / pkgsitex-init 三 entrypoint。
+#
+# Tag 策略：
+#   - fork-main：fork/main 分支 HEAD 永远指向最新（compose.prod.yaml 默认拉这个）
+#   - <git-sha>：每次 push 一份 immutable，方便 rollback
+#
+# 触发条件：fork/main 推送、PR 推送（PR 只 build 不 push 验证 Dockerfile）。
+#
+# 用户操作：
+#   1) https://hub.docker.com/settings/security 生成 access token
+#   2) GitHub repo Settings → Secrets and variables → Actions 加两个 secret：
+#        DOCKERHUB_USERNAME = nickwilde18
+#        DOCKERHUB_TOKEN    = <docker.io access token>
+#   3) push fork/main 触发本 workflow
+
+on:
+  push:
+    branches:
+      - fork/main
+  pull_request:
+    branches:
+      - master
+      - fork/main
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to Docker Hub
+        # PR 触发时跳过 login（forks PR 拿不到 secret，build 跑通验证 Dockerfile 即可）
+        if: github.event_name == 'push'
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: nickwilde18/pkgsitex
+          # tags：fork-main 浮动指向最新 / <sha> 不可变
+          tags: |
+            type=raw,value=fork-main,enable=${{ github.ref == 'refs/heads/fork/main' }}
+            type=sha,format=short,prefix=
+
+      - name: Set up QEMU
+        # 跨 arch build 需要 binfmt——QEMU emulation 让 amd64 runner 能交叉
+        # 编出 arm64 二进制（buildx + Go 交叉编译速度差距很小）
+        uses: docker/setup-qemu-action@v3
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: deploy/prod/Dockerfile
+          # PR 时只 build 不 push（验证 Dockerfile 不坏）
+          push: ${{ github.event_name == 'push' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          # 多 arch：macOS arm64 / 国产 CPU / 树莓派都能直接 docker pull
+          # native，省 Rosetta emulation；amd64 K8s prod 节点也照样 native
+          platforms: linux/amd64,linux/arm64
+          # 用 GitHub Actions cache 加速重 build
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
diff --git a/.gitignore b/.gitignore
@@ -51,3 +51,7 @@ __diff_output__
 #### Cloud Build Artifacts ####
 _BUILD_TAG
 _ID_TOKEN
+
+#### pkgsitex prod stack 配置 ####
+# .env 含 GITHUB_TOKEN 明文，绝对不能提交
+deploy/prod/.env
diff --git a/README.md b/README.md
@@ -1,78 +1,168 @@
-# golang.org/x/pkgsite
+# pkgsitex
 
-This repository hosts the source code of the [pkg.go.dev](https://pkg.go.dev) website,
-and [`pkgsite`](https://pkg.go.dev/golang.org/x/pkgsite/cmd/pkgsite), a documentation
-server program.
+> English ｜ [简体中文](README.zh-CN.md)
 
-[![Go Reference](https://pkg.go.dev/badge/golang.org/x/pkgsite.svg)](https://pkg.go.dev/golang.org/x/pkgsite)
+A fork of [`golang/pkgsite`](https://github.com/golang/pkgsite) tuned for self-hosting Go module docs in private/internal environments. Adds URL subpath mounting, godoc comment markdown (mermaid / inline code / bold), unexported symbol display + browser toggle, view source via locally mounted files, and config-driven private GitHub repo support.
 
-## pkg.go.dev: a site for discovering Go packages
+> **Fork strategy**: master always equals upstream master; all patches live on the long-lived [`fork/main`](https://github.com/NickWilde18/pkgsitex/tree/fork/main) branch. GitHub "Sync fork" stays fast-forward, zero conflict. All usage / setup / patch docs live on `fork/main` — including this README.
 
-Pkg.go.dev is a website for discovering and evaluating Go packages and modules.
+```sh
+git clone https://github.com/NickWilde18/pkgsitex.git ~/Repo/pkgsitex
+cd ~/Repo/pkgsitex
+git checkout fork/main          # switch to the fork patches branch
+cat README.md                   # ← what you're reading
+```
 
-You can check it out at [https://pkg.go.dev](https://pkg.go.dev).
+## Quick start (local, sub-second)
 
-## pkgsite: a documentation server
+Requires Go 1.25+. Clone the repos you want to browse to `~/Repo/<name>`.
 
-`pkgsite` program extracts and generates documentation for Go projects.
+```sh
+go run ./cmd/pkgsite -base-path=/pkgsitex -show-unexported -http=:8089 \
+    ~/Repo/Chat \
+    ~/Repo/Doubao-Speech-Service \
+    ~/Repo/UniAuth/uniauth-gf \
+    ~/Repo/UniAuth/ittools_sync \
+    ~/Repo/open-platform
 
-Example usage:
+open http://localhost:8089/pkgsitex/
+```
+
+Or compile once and reuse locally:
 
+```sh
+go install ./cmd/pkgsite
+pkgsite -base-path=/pkgsitex -show-unexported -http=:8089 ~/Repo/Chat ...
 ```
-$ go install golang.org/x/pkgsite/cmd/pkgsite@latest
-$ cd myproject
-$ pkgsite -open .
+
+The first `go run` fetches `esbuild` / `safehtml` deps via GOPROXY (~30s); subsequent runs are instant.
+
+## Configuration
+
+| flag | purpose | default |
+|---|---|---|
+| `-base-path=/pkgsitex` | mount the site under a URL subpath (reverse-proxy / shared-domain scenarios). Empty = mount at root (pkg.go.dev behavior) | `""` |
+| `-show-unexported` | godoc renders unexported declarations; the browser uses a toggle to control visibility | `false` |
+| `-http=:8089` | listen address | `localhost:8080` |
+| `-cache` | use GOMODCACHE | `false` |
+| `-proxy` | use GOPROXY to fetch remote modules | `false` |
+| `<path>...` | Go module paths to index (multiple) | `.` |
+
+Full flags: `go run ./cmd/pkgsite -h`.
+
+## Adding / removing repos
+
+Edit the path list at the end of the `go run` / `pkgsite` command.
+
+Convention: clone internal repos to `~/Repo/<name>`. UniAuth is a monorepo with two Go modules (`uniauth-gf/` + `ittools_sync/`) — list each separately; pkgsite doesn't auto-discover nested modules.
+
+## Browse experience
+
+| Element | Behavior |
+|---|---|
+| URL `/pkgsitex/<module>` | module overview |
+| URL `/pkgsitex/<module>/<sub>` | subpackage |
+| URL `/pkgsitex/<module>@<tag>` | specific git tag (local mode reads from module cache; the prod worker mode has full tag history) |
+| **Show unexported** button | next to the Index header — toggles visibility of private declarations / sidebar / index links; state persists in localStorage across pages |
+| **Show internal directories** button | upstream feature — toggles `internal/` subdirectory display. Auto-enabled when `data-local=true` |
+| ` `code` ` / `**bold**` / ` ```mermaid ` | godoc comments render these markdown forms (the fork's dochtml ext) |
+| **View Source** | a link next to each declaration on the package detail page — jumps to the locally mounted source file (no GitHub access required) |
+
+## Patches (what the fork changes)
+
+- **`-base-path`**: URL subpath prefix — all mux patterns / template helpers / godoc cross-references / view source links are auto-prefixed
+- **`-show-unexported`**: makes `internal/fetch/load.go` keep unexported `FuncDecl`s during AST processing, and `doc.NewFromFiles` uses `doc.AllDecls`
+- **godoc markdown ext** (`internal/godoc/dochtml/internal/render/markdown_ext.go`): post-processes HTML to recognize inline code / bold / mermaid fences
+- **mermaid client lazy-load** (`static/frontend/frontend.tmpl`): dynamically imports `mermaid@10` only when a page contains `code.language-mermaid`
+- **unexported toggle** (`static/frontend/unit/main/main.ts`): client-side hide + button + localStorage
+- **view source local file mux** + base path prefix fix
+- **multi-repo command line**: list multiple module paths in one command
+- **trailing-slash redirect-loop fix**: `internal/frontend/details.go` distinguishes "mounted at root" from "the base path itself" in base-path mode
+- **prod 4-piece stack**: postgres / athens / worker / frontend `compose.prod.yaml` plus a `cmd/pkgsitex-init` bootstrap container that writes athens netrc + enqueues modules to the worker
+
+## Prod deployment
+
+Prod mode differs from dev — it runs the same 4-component architecture as pkg.go.dev itself:
+
+- **postgres**: caches module index / package docs
+- **athens**: GOPROXY cache + private repo fetch via GitHub PAT
+- **worker**: async fetches modules into the DB
+- **frontend**: renders from the DB (port 8089)
+
+The image is published to docker.io: [`nickwilde18/pkgsitex:fork-main`](https://hub.docker.com/r/nickwilde18/pkgsitex) (multi-arch `linux/amd64` + `linux/arm64`, auto-pushed by GitHub Actions). Users don't need to build — pull the image and run.
+
+```sh
+git clone https://github.com/NickWilde18/pkgsitex.git
+cd pkgsitex
+git checkout fork/main
+
+# 1) configure PAT
+cp deploy/prod/.env.example deploy/prod/.env
+$EDITOR deploy/prod/.env             # GITHUB_TOKEN=ghp_xxx
+
+# 2) edit the module list (5 sample CUHKSZ internal repos pre-listed)
+$EDITOR deploy/prod/config.yaml
+
+# 3) start the stack (image is auto-pulled)
+docker compose -f compose.prod.yaml --env-file deploy/prod/.env up -d
+
+# 4) browse
+open http://localhost:8089/pkgsitex/
 ```
 
-For more information, see the [pkgsite documentation](https://pkg.go.dev/golang.org/x/pkgsite/cmd/pkgsite).
+Full ops (add/remove modules, periodic cron refresh, troubleshooting): [`deploy/prod/README.md`](deploy/prod/README.md).
 
-## API
+Supports multi-version (git tag switching), license-permissive rendering (proprietary too), and config-driven module list.
 
-`pkgsite` provides a REST API for retrieving package and module information.
-The API endpoints include:
+## Maintenance strategy
 
-- `/v1/package/{path}`: Information about the package at `{path}`.
-- `/v1/module/{path}`: Information about the module at `{path}`.
-- `/v1/versions/{path}`: Versions of the module at `{path}`.
-- `/v1/packages/{path}`: Information about packages of the module at `{path}`.
-- `/v1/search`: Search results.
-- `/v1/symbols/{path}`: List of symbols for the package at `{path}`.
-- `/v1/imported-by/{path}`: Paths of packages importing the package at `{path}`.
-- `/v1/vulns/{path}`: Vulnerabilities of the module at `{path}`.
+- **master always equals upstream master** — never merge `fork/main` into master. GitHub "Sync fork" stays fast-forward, zero conflict
+- **`fork/main` is a long-lived patch branch** — all fork changes accumulate here
+- **Monthly rebase**: AI runs `git rebase upstream/master` so `fork/main` follows new upstream development. Predicted conflict hot spots:
+  - `internal/frontend/server.go` mux list (when upstream adds new routes)
+  - `static/**/*.tmpl` / `*.ts` (when upstream changes styles / interactions)
+  - other fork-only files (e.g. `markdown_ext.go`, `base-path/base-path.ts`) almost never conflict (fork-exclusive)
 
-For detailed documentation of parameters and response schemas, see the documentation page served at `/api`, or refer directly to the annotated source code in `internal/api/api.go`.
+Patch history: PR [#2](https://github.com/NickWilde18/pkgsitex/pull/2).
 
-## Issues
+## Troubleshooting
 
-If you want to report a bug or have a feature suggestion, please first check
-the [known issues](https://github.com/golang/go/labels/pkgsite) to see if your
-issue is already being discussed. If an issue does not already exist, feel free
-to [file an issue](https://golang.org/s/pkgsite-feedback).
+| Symptom | Diagnosis |
+|---|---|
+| `go run` fails to fetch deps | use a closer GOPROXY: `GOPROXY=https://goproxy.cn,direct go run ...` |
+| `/pkgsitex/...` static asset 404 | you edited `static/`/templates without rebuilding: run `go run ./devtools/cmd/static` to regenerate the bundle |
+| module resolution timeout | point GOPROXY at the company Athens: `export GOPROXY=https://athens.corp.com,direct` |
+| mermaid doesn't render | check the browser console for `mermaid load failed` — your network blocks jsdelivr CDN; vendor mermaid locally (`third_party/mermaid/` pending) |
+| Sidebar / Index has no "Show unexported" button | localStorage may have an old toggle key (`gogodocs:showUnexported`); click the button once to reset to the new key |
 
-For answers to frequently asked questions, see [pkg.go.dev/about](https://pkg.go.dev/about).
+---
 
-You can also chat with us on the
-[#pkgsite Slack channel](https://gophers.slack.com/archives/C0166L4QGJV) on the
-[Gophers Slack](https://invite.slack.golangbridge.org).
+## Upstream pkgsite
 
-## Contributing
+A downstream fork has to follow upstream development — keeping the upstream README content below for cross-checking features / locating differences during upgrades.
+
+# golang.org/x/pkgsite
+
+This repository hosts the source code of the [pkg.go.dev](https://pkg.go.dev) website,
+and [`pkgsite`](https://pkg.go.dev/golang.org/x/pkgsite/cmd/pkgsite), a documentation
+server program.
 
-We would love your help!
+[![Go Reference](https://pkg.go.dev/badge/golang.org/x/pkgsite.svg)](https://pkg.go.dev/golang.org/x/pkgsite)
 
-Our canonical Git repository is located at
-[go.googlesource.com/pkgsite](https://go.googlesource.com/pkgsite).
-There is a mirror of the repository at
-[github.com/golang/pkgsite](https://github.com/golang/pkgsite).
+Full upstream README: [golang/pkgsite README](https://github.com/golang/pkgsite#readme).
 
-To contribute, please read our [contributing guide](CONTRIBUTING.md).
+## Issues
 
-## License
+Fork issues (base-path / markdown ext / etc): [NickWilde18/pkgsitex/issues](https://github.com/NickWilde18/pkgsitex/issues).
 
-Unless otherwise noted, the Go source files are distributed under the BSD-style
-license found in the [LICENSE](LICENSE) file.
+Upstream pkgsite issues go to [`golang/go`](https://golang.org/issues), prefixed `x/pkgsite:` — see the upstream README.
 
-## Links
+## Contributing
+
+Fork-internal PRs target the `fork/main` branch (not master).
+
+Upstream pkgsite contribution flow (Gerrit code review): [Contribution Guide](https://golang.org/doc/contribute.html) + [upstream README contributing section](https://github.com/golang/pkgsite#contributing).
+
+## License
 
-- [Homepage](https://pkg.go.dev)
-- [Feedback](https://golang.org/s/pkgsite-feedback)
-- [Issue Tracker](https://golang.org/s/pkgsite-issues)
+Unless otherwise noted, the source files are distributed under the BSD-style license found in the LICENSE file.