----------------------------------------
          企多客 CMS V1.0 使用说明
----------------------------------------

一、产品简介

企多客 CMS 是面向内容站点与多站点运营场景的内容管理系统，适用于企业官网、内容门户、行业资讯、知识专栏及专题站点建设。

主要能力包括：
1. 多站点统一管理；
2. 栏目、文章、独立页面和导航管理；
3. 多主题切换、主题变量配置和自定义主题；
4. 文章分发、Open API 接入及调用审计；
5. 访问量统计与站点运营分析；
6. sitemap.xml、robots.txt、llms.txt、Open Graph 和结构化数据等 SEO/AEO 能力；
7. 本地文件存储、渲染缓存及健康检查。

二、运行环境

1. 操作系统
   64 位 Windows Server。建议使用仍处于微软支持周期内的版本。

2. Web 服务器
   IIS，需安装 ASP.NET Core Module V2。
   建议应用程序池设置为“无托管代码”，并使用 64 位进程。

3. 运行时
   .NET 8 Hosting Bundle（包含 ASP.NET Core 8 Runtime）。
   本发布包为框架依赖部署，服务器必须预先安装对应运行时。

4. 数据服务
   PostgreSQL 15 或更高版本。
   Redis 为必需依赖，建议使用 Redis 5.x 或更高版本。

5. 权限与网络
   IIS 应用程序池身份需对程序配置目录、App_Data 目录和数据目录拥有必要的读写权限。
   服务器需能够访问所配置的 PostgreSQL 与 Redis 服务。

三、发布包目录

QiDuoKeCMS-V1.0\
├─ CMS\
│  ├─ Service\                 网站程序目录，也是 IIS 站点物理路径
│  │  ├─ Settings\            基础配置与安装后生成的本地配置
│  │  ├─ App_Data\            安装状态、初始化脚本和运行日志
│  │  ├─ wwwroot\             控制台静态资源与站点主题
│  │  └─ web.config            IIS 托管配置
│  └─ Data\
│     └─ Sites\               建议用于保存上传图片和站点文件
└─ Docs\
   ├─ readme.txt               本使用说明
   └─ license.txt              软件使用许可声明

重要配置文件：
1. CMS\Service\Settings\appsettings.json：基础配置。
2. CMS\Service\Settings\appsettings.Local.json：安装向导生成的数据库与 Redis 连接配置。
3. CMS\Service\App_Data\install\.installed：安装完成标记，请勿随意删除。
4. CMS\Service\App_Data\logs\：运行日志目录。

四、安装前准备

1. 安装 IIS，并安装 .NET 8 Hosting Bundle；安装完成后重启 IIS。
2. 准备 PostgreSQL 15+。安装账号应能连接目标实例；如需由向导自动创建数据库，该账号还需具有 CREATE DATABASE 权限。
3. 准备可用的 Redis 服务。
4. 将完整发布包解压到正式目录，不要直接在压缩包内运行。
5. 编辑 CMS\Service\Settings\appsettings.json：
   (1) 将 DataPath 设置为服务器上的绝对路径，建议指向本发布包的 CMS\Data 目录；
   (2) 将 SiteFarm.Console.JwtSecret 替换为足够长的随机密钥；
   (3) 如有统一域名，可按部署情况配置 SiteFarm.BaseUrl。
6. 为 IIS 应用程序池身份授予以下目录的修改权限：
   CMS\Service\Settings\
   CMS\Service\App_Data\
   CMS\Data\

请勿把数据库密码、Redis 密码、JWT 密钥或安装令牌提交到公开代码仓库。

五、IIS 部署

1. 在 IIS 中新建网站，物理路径选择 CMS\Service。
2. 根据实际环境配置域名、HTTP/HTTPS 端口与证书。
3. 应用程序池选择“无托管代码”，并启用 64 位进程。
4. 启动网站后访问：
   https://您的域名/setup
5. 如果站点尚未安装，访问其他页面也会自动跳转到安装向导。

六、首次安装向导

安装向导共五步：

1. 数据库
   填写 PostgreSQL 主机、端口、数据库名、用户名和密码。
   默认端口为 5432。目标数据库不存在时，向导会尝试自动创建。

2. Redis
   填写 Redis 主机、端口、密码和 DB 索引。
   默认端口为 6379。

3. 结构导入
   系统按顺序执行 CMS\Service\App_Data\install\schema\ 中的 SQL 脚本。

4. 管理员
   创建首个超级管理员。用户名至少 3 个字符，密码至少 6 个字符；生产环境请使用更强密码。

5. 完成初始化
   系统写入本地连接配置、创建安装标记并扫描内置主题。完成后需重启 IIS 网站或回收应用程序池，使全部连接配置生效。

安装令牌：
首次启动且系统尚未安装时，会生成一次性安装令牌。可在以下文件中读取：
CMS\Service\App_Data\install\.install-token

复制令牌并粘贴到安装向导。初始化完成后，该令牌会被自动清理。

七、登录与常用入口

管理控制台：
https://您的域名/console/

登录页面：
https://您的域名/console/login

健康检查：
https://您的域名/healthz

健康检查正常时返回：ok
注意：该地址仅用于确认 Web 进程存活，不代表 PostgreSQL、Redis 和全部业务功能均已就绪。

八、数据与主题

1. 上传文件保存在 DataPath 指定目录中，内部按 sites/{分类}/{年}/{月}/ 组织。
2. 内置与自定义主题位于 CMS\Service\wwwroot\themes\。
3. 修改主题后，可在控制台执行主题扫描；前台渲染缓存默认约 5 分钟，也可通过控制台的缓存失效功能立即刷新。
4. 自定义域名使用前，应同时完成 DNS 解析、IIS 绑定和站点域名配置。

九、备份与升级

升级或迁移前，至少备份以下内容：
1. PostgreSQL 数据库；
2. CMS\Data 或 DataPath 指向的整个数据目录；
3. CMS\Service\Settings\appsettings.Local.json；
4. CMS\Service\App_Data\install\.installed；
5. 自定义过的 CMS\Service\wwwroot\themes\ 目录。

建议升级流程：
1. 停止 IIS 网站或应用程序池；
2. 完成数据库和文件备份；
3. 按升级包说明替换程序文件，并保留本地配置、安装标记、上传文件和自定义主题；
4. 如升级包包含数据库迁移脚本，按说明执行；
5. 启动网站，检查 /healthz、控制台登录、站点访问和文件上传；
6. 确认无误后再恢复对外流量。

不要直接清空或覆盖 CMS\Service\App_Data 和 CMS\Service\Settings 目录，否则可能丢失安装状态与连接配置。

十、常见问题

1. 网站启动后显示 500
   检查 .NET 8 Hosting Bundle、IIS 应用程序池设置、目录权限及运行日志。

2. 安装令牌无效
   重新读取 CMS\Service\App_Data\install\.install-token，确认没有复制空格或换行，并确保正在访问同一台服务器实例。

3. 数据库无法创建
   确认 PostgreSQL 地址与端口可访问，账号密码正确，并具有创建数据库和执行建表脚本的权限。

4. Redis 连接失败
   检查 Redis 服务状态、防火墙、端口、密码和 DB 索引。

5. 图片上传失败或无法访问
   确认 DataPath 为有效的绝对路径，并确保 IIS 应用程序池身份对该目录拥有读写权限。

6. 安装完成后仍提示需要安装
   确认 CMS\Service\App_Data\install\.installed 文件存在，并检查 App_Data 目录权限；然后回收应用程序池。

7. 修改主题后页面未立即更新
   在控制台清理站点渲染缓存，或等待缓存自动过期。

十一、安全建议

1. 正式环境必须启用 HTTPS。
2. 修改默认 JWT 密钥，并使用强管理员密码。
3. PostgreSQL 与 Redis 不应直接暴露到公网。
4. 定期备份并执行恢复演练。
5. 定期安装操作系统、.NET、PostgreSQL 和 Redis 安全更新。
6. 按最小权限原则设置数据库账号、应用程序池身份和目录访问权限。
7. 定期检查 CMS\Service\App_Data\logs\ 中的异常登录、接口错误和安全告警。

十二、技术支持

产品更新、授权咨询、部署支持及服务范围，以正式购买渠道、交付清单或双方签署的服务协议为准。

产品名称：企多客 CMS
文档版本：1.0
发布日期：2026 年 9 月 1 日
