diff --git a/modules/web/route.go b/modules/web/route.go
index b1073cc169..34290bd8e5 100644
--- a/modules/web/route.go
+++ b/modules/web/route.go
@@ -194,8 +194,9 @@ func (r *Route) normalizeRequestPath(resp http.ResponseWriter, req *http.Request
 		normalizedPath = buf.String()
 	}
 
-	// if the config tells Gitea to use a sub-url path directly without reverse proxy,
-	// then we need to remove the sub-url path from the request URL path
+	// If the config tells Gitea to use a sub-url path directly without reverse proxy,
+	// then we need to remove the sub-url path from the request URL path.
+	// But "/v2" is special for OCI container registry, it should always be in the root of the site.
 	if setting.UseSubURLPath {
 		remainingPath, ok := strings.CutPrefix(normalizedPath, setting.AppSubURL+"/")
 		if ok {
diff --git a/modules/web/route_test.go b/modules/web/route_test.go
index 45dfdc484d..c5595a02a3 100644
--- a/modules/web/route_test.go
+++ b/modules/web/route_test.go
@@ -215,6 +215,7 @@ func TestRouteNormalizePath(t *testing.T) {
 	testPath("/sub-path/", paths{EscapedPath: "/", RawPath: "/", Path: "/"})
 	testPath("/sub-path//a/b///", paths{EscapedPath: "/a/b", RawPath: "/a/b", Path: "/a/b"})
 	testPath("/sub-path/%2f/", paths{EscapedPath: "/%2f", RawPath: "/%2f", Path: "//"})
+	// "/v2" is special for OCI container registry, it should always be in the root of the site
 	testPath("/v2", paths{EscapedPath: "/v2", RawPath: "/v2", Path: "/v2"})
 	testPath("/v2/", paths{EscapedPath: "/v2", RawPath: "/v2", Path: "/v2"})
 	testPath("/v2/%2f", paths{EscapedPath: "/v2/%2f", RawPath: "/v2/%2f", Path: "/v2//"})
diff --git a/routers/init.go b/routers/init.go
index 56c95cd1ca..5cf40a4151 100644
--- a/routers/init.go
+++ b/routers/init.go
@@ -191,7 +191,8 @@ func NormalRoutes() *web.Route {
 	if setting.Packages.Enabled {
 		// This implements package support for most package managers
 		r.Mount("/api/packages", packages_router.CommonRoutes())
-		// This implements the OCI API (Note this is not preceded by /api but is instead /v2)
+		// This implements the OCI API, this container registry "/v2" endpoint must be in the root of the site.
+		// If site admin deploys Gitea in a sub-path, they must configure their reverse proxy to map the "https://host/v2" endpoint to Gitea.
 		r.Mount("/v2", packages_router.ContainerRoutes())
 	}