@atomservice/gitea 0.1.5

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@atomservice/gitea",
+  "version": "0.1.5",
+  "description": "Gitea 原子服务",
+  "type": "module",
+  "author": "openorson",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openorson/atomservice.git",
+    "directory": "services/gitea"
+  },
+  "bugs": "https://github.com/openorson/atomservice/issues",
+  "homepage": "https://github.com/openorson/atomservice/tree/main/services/gitea#readme",
+  "keywords": [
+    "atomservice",
+    "gitea",
+    "git",
+    "self-hosted",
+    "podman"
+  ],
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@atomservice/gateway": "0.1.5"
+  },
+  "peerDependencies": {
+    "@atomservice/core": "0.1.5"
+  }
+}

package/src/gitea.compose.ts

@@ -0,0 +1,60 @@
+import { tmpl } from "@atomservice/core"
+import { GITEA_IMAGE } from "./gitea.consts.ts"
+
+export interface GiteaComposeOptions {
+  rootless: boolean
+  environment?: Record<string, string>
+  hostPort?: number
+  sshHostPort?: number
+}
+
+export function giteaCompose(id: string, version: string, dataDir: string, opts: GiteaComposeOptions): string {
+  const { rootless, environment, hostPort, sshHostPort } = opts
+  const port = 3000
+  const uid = 1000
+  const gid = 1000
+
+  const imageTag = rootless ? `${version}-rootless` : version
+  const volumeTarget = rootless ? "/var/lib/gitea" : "/data"
+  const containerSshPort = rootless ? 2222 : 22
+
+  const httpPort = hostPort ? `\n      - "${hostPort}:${port}"` : ""
+  const sshPort = sshHostPort ? `\n      - "${sshHostPort}:${containerSshPort}"` : ""
+  const portsBlock = httpPort || sshPort ? `\n    ports:${httpPort}${sshPort}` : ""
+
+  const sshEnv =
+    rootless && sshHostPort ? `\n      - SSH_PORT=${sshHostPort}\n      - SSH_LISTEN_PORT=${containerSshPort}` : ""
+
+  const envBlock =
+    environment && Object.keys(environment).length > 0
+      ? `\n${Object.entries(environment)
+          .map(([k, v]) => `      - ${k}=${v}`)
+          .join("\n")}`
+      : ""
+
+  return tmpl`\
+services:
+  ${id}:
+    image: ${GITEA_IMAGE}:${imageTag}
+    container_name: ${id}
+    environment:${envBlock}
+      - USER_UID=${uid}
+      - USER_GID=${gid}${sshEnv}${portsBlock}
+    volumes:
+      - ${dataDir}:${volumeTarget}
+    networks:
+      - atomservice
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-sf", "http://localhost:${port}/api/healthz"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 15s
+
+networks:
+  atomservice:
+    name: atomservice
+    external: true
+`
+}

package/src/gitea.consts.ts

@@ -0,0 +1 @@
+export const GITEA_IMAGE = "docker.gitea.com/gitea"

package/src/gitea.instance.ts

@@ -0,0 +1,33 @@
+export interface GiteaInstance {
+  /**
+   * 容器主机名
+   *
+   * - 同容器名
+   * - 容器网络内可直接访问
+   */
+  readonly host: string
+  /**
+   * 容器内 `HTTP` 监听端口
+   */
+  readonly port: number
+  /**
+   * 容器内 `SSH` 监听端口
+   *
+   * - `rootful` 为 `22`
+   * - `rootless` 为 `2222`
+   */
+  readonly sshPort: number
+  /**
+   * 容器网络内访问地址
+   *
+   * - 如 `http://gitea:3000/`
+   */
+  readonly url: string
+  /**
+   * 对外域名地址
+   *
+   * - 如 `https://git.example.com/`
+   * - 仅配置 `domain` 后可用
+   */
+  readonly externalUrl: string | undefined
+}

package/src/gitea.options.ts

@@ -0,0 +1,75 @@
+import type { CallableService } from "@atomservice/core"
+import type { GatewayInstance } from "@atomservice/gateway"
+
+export interface GiteaOptions {
+  /**
+   * 实例标识
+   *
+   * - 用于区分不同实例
+   *
+   * @default "default"
+   */
+  id?: string
+  /**
+   * 镜像版本
+   *
+   * @default "1"
+   */
+  version?: string
+  /**
+   * 映射到宿主机的端口
+   *
+   * - 不填则不对外暴露，仅容器网络内访问
+   */
+  hostPort?: number
+  /**
+   * 对外域名
+   *
+   * - 填写后自动在网关注册反代路由
+   * - 需要和 `gateway` 原子一起使用
+   */
+  domain?: string
+  /**
+   * `SSH` 映射到宿主机的端口
+   *
+   * - 不设置则仅支持 `HTTP(S)` 方式克隆
+   * - 填写后额外支持 `git@host:org/repo.git` 克隆
+   * - 建议使用 `2222`，避免与宿主机默认 `SSH` 端口 `22` 冲突
+   */
+  sshHostPort?: number
+  /**
+   * 使用 `rootless` 镜像
+   *
+   * - `rootless` 安全性更高，但权限要求更严格
+   * - 一旦初始化数据目录后不可切换 `rootful` / `rootless`
+   *
+   * @default false
+   */
+  rootless?: boolean
+  /**
+   * 自定义环境变量
+   *
+   * - 支持 Gitea 的 `GITEA__section__KEY` 格式
+   * - 用于配置数据库、邮件等任意 `app.ini` 设置
+   *
+   * @example
+   * ```ts
+   * // 配置 SMTP 邮件
+   * environment: {
+   *   GITEA__mailer__ENABLED: "true",
+   *   GITEA__mailer__FROM: "noreply@example.com",
+   *   GITEA__mailer__HOST: "smtp.example.com:587",
+   *   GITEA__mailer__USER: "noreply@example.com",
+   *   GITEA__mailer__PASSWD: "xxx",
+   * }
+   * ```
+   */
+  environment?: Record<string, string>
+  /**
+   * 网关原子实例
+   *
+   * - 填写后自动向网关注册反代路由
+   * - 通常和 `domain` 一起使用
+   */
+  gateway?: CallableService<GatewayInstance>
+}

package/src/gitea.service.ts

@@ -0,0 +1,105 @@
+import path from "node:path"
+import type { CallableService } from "@atomservice/core"
+import { defineService, onDown, onHealth, onUp, useConfig, useLogger, useShell, useState } from "@atomservice/core"
+import { giteaCompose } from "./gitea.compose.ts"
+import type { GiteaInstance } from "./gitea.instance.ts"
+import type { GiteaOptions } from "./gitea.options.ts"
+import type { GiteaState } from "./gitea.types.ts"
+
+export function gitea(opts: GiteaOptions = {}): CallableService<GiteaInstance> {
+  const serviceId = opts.id && opts.id !== "default" ? opts.id : "default"
+  const containerName = serviceId !== "default" ? `gitea-${serviceId}` : "gitea"
+  const version = opts.version ?? "1"
+  const rootless = opts.rootless ?? false
+
+  return defineService({
+    name: "gitea",
+    id: opts.id,
+    setup: () => {
+      const logger = useLogger()
+      const $ = useShell()
+      const config = useConfig()
+      const gw = opts.gateway?.()
+
+      const dir = path.join(config.root, containerName)
+      const composePath = path.join(dir, "compose.yml")
+
+      const { save, watch, checkChanges } = useState<GiteaState>()
+
+      watch("version", {
+        risk: "low",
+        changed: (previousValue, currentValue) =>
+          `Gitea 版本已变更 ${previousValue} → ${currentValue}，将在下次启动时拉取新镜像`,
+      })
+
+      watch("rootless", {
+        risk: "high",
+        changed: () => `rootless 模式已切换，rootful 与 rootless 镜像不兼容，已有数据目录无法复用`,
+      })
+
+      onUp(async () => {
+        const currentState: GiteaState = { version, rootless }
+        await checkChanges(currentState)
+
+        await $`mkdir -p ${dir}/data`
+        await Bun.write(
+          composePath,
+          giteaCompose(containerName, version, `${dir}/data`, {
+            rootless,
+            environment: opts.environment,
+            hostPort: opts.hostPort,
+            sshHostPort: opts.sshHostPort,
+          }),
+        )
+
+        logger.info(`正在启动 ${containerName}`)
+        await $`podman compose -f ${composePath} up -d`
+        logger.success(`${containerName} 已启动`)
+
+        if (opts.domain && gw) {
+          logger.info(`注册路由 ${opts.domain} → ${containerName}:3000`)
+          await gw.registerRoute(opts.domain, `${containerName}:3000`)
+          logger.success(`路由已注册，访问 https://${opts.domain}`)
+        }
+
+        await save(currentState)
+      })
+
+      onDown(async () => {
+        logger.info(`正在停止 ${containerName}`)
+        await $`podman compose -f ${composePath} down`
+        logger.success(`${containerName} 已停止`)
+      })
+
+      onHealth(async () => {
+        try {
+          const result = await $`podman exec ${containerName} curl -sf http://localhost:3000/api/healthz`
+            .quiet()
+            .nothrow()
+          if (result.exitCode === 0) return { status: "healthy" }
+          return { status: "unhealthy", message: `Gitea 健康检查返回 ${result.exitCode}` }
+        } catch {
+          return { status: "unhealthy", message: `容器 ${containerName} 不存在` }
+        }
+      })
+
+      return {
+        get host() {
+          return containerName
+        },
+        get port() {
+          return 3000
+        },
+        get sshPort() {
+          return rootless ? 2222 : 22
+        },
+        get url() {
+          return `http://${containerName}:3000/`
+        },
+        get externalUrl() {
+          return opts.domain ? `https://${opts.domain}/` : undefined
+        },
+      }
+    },
+  })
+}

package/src/gitea.types.ts

@@ -0,0 +1,4 @@
+export type GiteaState = {
+  version: string
+  rootless: boolean
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export type { GiteaInstance } from "./gitea.instance.ts"
+export type { GiteaOptions } from "./gitea.options.ts"
+export { gitea } from "./gitea.service.ts"