@atomservice/redis 0.1.5

package/package.json

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

package/src/index.ts

@@ -0,0 +1,3 @@
+export type { RedisInstance } from "./redis.instance.ts"
+export type { RedisOptions } from "./redis.options.ts"
+export { redis } from "./redis.service.ts"

package/src/redis.compose.ts

@@ -0,0 +1,40 @@
+import { tmpl } from "@atomservice/core"
+import { REDIS_CONF_PATH, REDIS_IMAGE } from "./redis.consts.ts"
+import type { RedisOptions } from "./redis.options.ts"
+
+export function redisCompose(
+  containerName: string,
+  version: string,
+  dataDir: string,
+  confPath: string,
+  opts: Pick<RedisOptions, "password" | "hostPort">,
+): string {
+  const { password, hostPort } = opts
+
+  const portsBlock = hostPort ? `\n    ports:\n      - "${hostPort}:6379"` : ""
+  const authEnv = password ? `\n    environment:\n      - REDISCLI_AUTH=${password}` : ""
+
+  return tmpl`\
+services:
+  ${containerName}:
+    image: ${REDIS_IMAGE}:${version}-alpine
+    container_name: ${containerName}
+    command: redis-server ${REDIS_CONF_PATH}${authEnv}
+    volumes:
+      - ${dataDir}:/data
+      - ${confPath}:${REDIS_CONF_PATH}:ro${portsBlock}
+    networks:
+      - atomservice
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+networks:
+  atomservice:
+    name: atomservice
+    external: true
+`
+}

package/src/redis.consts.ts

@@ -0,0 +1,2 @@
+export const REDIS_IMAGE = "redis"
+export const REDIS_CONF_PATH = "/usr/local/etc/redis/redis.conf"

package/src/redis.instance.ts

@@ -0,0 +1,25 @@
+export interface RedisInstance {
+  /**
+   * 容器 `hostname`
+   */
+  readonly host: string
+  /**
+   * 容器内端口
+   */
+  readonly port: 6379
+  /**
+   * 访问密码
+   *
+   * - 未设置密码时为 `undefined`
+   */
+  readonly password: string | undefined
+  /**
+   * 获取连接字符串
+   *
+   * @param db Redis 逻辑库编号（0-15），默认 0
+   *
+   * @example 有密码 `redis().connectionString()` → `redis://:password@redis:6379/0`
+   * @example 无密码 `redis().connectionString(1)` → `redis://redis:6379/1`
+   */
+  connectionString(db?: number): string
+}

package/src/redis.options.ts

@@ -0,0 +1,58 @@
+export interface RedisOptions {
+  /**
+   * 实例标识
+   *
+   * - 用于区分不同实例
+   *
+   * @default "default"
+   */
+  id?: string
+  /**
+   * 镜像版本
+   *
+   * @default "8"
+   */
+  version?: string
+  /**
+   * 访问密码
+   *
+   * - 不填则不设置密码（仅限容器内网访问时可不设）
+   */
+  password?: string
+  /**
+   * 映射到宿主机的端口
+   *
+   * - 不填则不对外暴露，仅容器网络内访问
+   */
+  hostPort?: number
+  /**
+   * 内存上限
+   *
+   * - 建议生产环境必设置，防止 `Redis` 吃满宿主机内存导致 `OOM`
+   * - 支持 Redis 原生格式：`"256mb"` / `"1gb"` 等
+   * - 不设置则无限制
+   */
+  maxMemory?: string
+  /**
+   * 内存淘汰策略
+   *
+   * - 仅在设置了 `maxMemory` 时生效
+   * - `allkeys-lru`：淘汰最久未使用的 `key`（适合纯缓存场景）
+   * - `volatile-lru`：只淘汰设置了过期时间的 `key`
+   * - `noeviction`：不淘汰，写满后报错（适合 `Session` / 队列等不能丢数据的场景）
+   *
+   * @default "allkeys-lru"
+   */
+  maxMemoryPolicy?: "allkeys-lru" | "allkeys-lfu" | "volatile-lru" | "volatile-lfu" | "volatile-ttl" | "noeviction"
+  /**
+   * 持久化方式
+   *
+   * - `"aof"`：`Append-Only File`，每次写操作追加日志，数据最安全（默认）
+   * - `"rdb"`：周期性快照，性能好但可能丢失最近数据
+   * - `"both"`：同时开启 `AOF` 和 `RDB`，兼顾性能和安全
+   * - `"none"`：不持久化，重启数据全部丢失（纯缓存场景可用）
+   *
+   * @default "aof"
+   */
+  persistence?: "aof" | "rdb" | "both" | "none"
+}

package/src/redis.service.ts

@@ -0,0 +1,100 @@
+import path from "node:path"
+import type { CallableService } from "@atomservice/core"
+import { defineService, onDown, onHealth, onUp, useConfig, useLogger, useShell, useState } from "@atomservice/core"
+import { redisCompose } from "./redis.compose.ts"
+import type { RedisInstance } from "./redis.instance.ts"
+import type { RedisOptions } from "./redis.options.ts"
+import type { RedisState } from "./redis.types.ts"
+import { buildRedisConf } from "./redis.utils.ts"
+
+export function redis(opts: RedisOptions = {}): CallableService<RedisInstance> {
+  const serviceId = opts.id && opts.id !== "default" ? opts.id : "default"
+  const containerName = serviceId !== "default" ? `redis-${serviceId}` : "redis"
+  const version = opts.version ?? "8"
+
+  return defineService({
+    name: "redis",
+    id: opts.id,
+    setup: () => {
+      const $ = useShell()
+      const config = useConfig()
+      const logger = useLogger()
+
+      const dir = path.join(config.root, containerName)
+      const composePath = path.join(dir, "compose.yml")
+      const confPath = path.join(dir, "redis.conf")
+
+      const { save, watch, checkChanges } = useState<RedisState>()
+
+      watch("version", {
+        risk: "low",
+        changed: (previousValue, currentValue) =>
+          `Redis 版本已变更 ${previousValue} → ${currentValue}，将在下次启动时拉取新镜像`,
+      })
+
+      watch("password", {
+        risk: "high",
+        added: () => `已新增密码认证，需重启容器并更新所有客户端连接字符串`,
+        removed: () => `已移除密码认证，需重启容器并更新所有客户端连接字符串`,
+        changed: () => `密码已变更，需重启容器并更新所有客户端连接字符串`,
+      })
+
+      onUp(async () => {
+        const currentState: RedisState = { version, password: opts.password }
+        await checkChanges(currentState)
+
+        await $`mkdir -p ${dir}/data`
+        await Bun.write(confPath, buildRedisConf(opts))
+        await Bun.write(composePath, redisCompose(containerName, version, `${dir}/data`, confPath, opts))
+
+        logger.info(`正在启动 ${containerName}`)
+        await $`podman compose -f ${composePath} up -d`
+        logger.success(`${containerName} 已启动`)
+
+        await save(currentState)
+      })
+
+      onDown(async () => {
+        logger.info(`停止 ${containerName}…`)
+        await $`podman compose -f ${composePath} down`
+        logger.success(`${containerName} 已停止`)
+      })
+
+      onHealth(async () => {
+        try {
+          const result = opts.password
+            ? await $`podman exec -e ${`REDISCLI_AUTH=${opts.password}`} ${containerName} redis-cli ping`.text()
+            : await $`podman exec ${containerName} redis-cli ping`.text()
+          if (result.trim() === "PONG") return { status: "healthy" }
+          return {
+            status: "unhealthy",
+            message: `redis-cli ping 返回：${result.trim()}`,
+          }
+        } catch {
+          return {
+            status: "unhealthy",
+            message: `容器 ${containerName} 不存在`,
+          }
+        }
+      })
+
+      return {
+        get host() {
+          return containerName
+        },
+        get port(): 6379 {
+          return 6379
+        },
+        get password() {
+          return opts.password
+        },
+        connectionString(db = 0): string {
+          const base = opts.password
+            ? `redis://:${opts.password}@${containerName}:6379`
+            : `redis://${containerName}:6379`
+          return `${base}/${db}`
+        },
+      }
+    },
+  })
+}

package/src/redis.types.ts

@@ -0,0 +1,4 @@
+export type RedisState = {
+  version: string
+  password: string | undefined
+}

package/src/redis.utils.ts

@@ -0,0 +1,16 @@
+import type { RedisOptions } from "./redis.options.ts"
+
+export function buildRedisConf(
+  opts: Pick<RedisOptions, "password" | "maxMemory" | "maxMemoryPolicy" | "persistence">,
+): string {
+  const { password, maxMemory, maxMemoryPolicy = "allkeys-lru", persistence = "aof" } = opts
+  const lines: string[] = []
+  if (password) lines.push(`requirepass ${password}`)
+  if (persistence === "aof" || persistence === "both") lines.push("appendonly yes")
+  if (persistence === "rdb" || persistence === "both") lines.push("save 3600 1 300 100 60 10000")
+  if (maxMemory) {
+    lines.push(`maxmemory ${maxMemory}`)
+    lines.push(`maxmemory-policy ${maxMemoryPolicy}`)
+  }
+  return lines.length ? `${lines.join("\n")}\n` : ""
+}